← More from code, and code examples
How do places work (mentions, poses, claims)?
Short answer
Bind words to a place with /base/geo/bind, work out a position with /base/geo/compose, and record where someone is with /base/geo/place-claims.
Before you start
Your app holds a person's sign-in token and its key.
Words used here (5)
- record
- A record is one piece of data with its own address, such as a person, a place, a thing or a note.
- sign-in token
- A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
- record's address
- A record's address is the web address that names one record for good: it never changes and is never given to another record.
- place claim
- A place claim is a record saying that someone lives at or is at a catalogue place, kept in the vault of whoever said it.
- vault's address
- A vault's address is the web address that names one vault, made from the vault's name, such as https://example-name.gilb.com/vault.
Steps
Turn the words for a place into a place.
Send mention, the words, as JSON, with the token and a new DPoP proof:
POST https://geo.gilb.com/base/geo/bindMore about this
A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). GilbPlatform looks for the words in the place catalogue, the vault https://geo.gilb.com/base that holds the world's named places, which anyone may read. The answer has id, the place's address; aliases, the name that matched; point, its point as EWKT, a standard way to write a shape as text, or null; confidence, from 0 to 1; and jurisdiction, the region it belongs to, or itself for a region. Case, accents and punctuation do not count. The same name scores 1, a name that starts with the words 0.85, a name with all the words 0.8. Under 0.7, or with two places less than 0.15 apart, the answer is no place: id null, not the nearest guess.
Work out where a thing sits through its frames.
Send entity, a record's address, and, if you like, target, the frame to stop at, to the host of the vault the record is in:
POST https://<name>.gilb.com/base/geo/composeMore about this
A record says where it sits in a:frameParent, the record it is measured from, and a:frameOffset, tx ty tz in metres, or tx ty tz qw qx qy qz with a turn. GilbPlatform walks up at most 16 frames and adds them up. The answer has entity; target, the frame you named, or, if you named none, the address where the walk stopped; pose, its position there, x, y, z, and its turn, qw, qx, qy, qz; and hops, the frames read. The walk stops at target, at a record with no a:frameParent, or at one you may not read or that is not there: those two look the same, so you learn nothing about what you may not read.
Record where someone lives or is.
Send subject, kind, placeUri, claimantVault and claimantHost as JSON to that vault's host:
POST https://<name>.gilb.com/base/geo/place-claimsMore about this
subject is the address of the person the claim is about; kind is lives-at or present-at; placeUri is an id from step 1; claimantVault is the address of the vault the claim is kept in, and claimantHost its host, such as <name>.gilb.com. The answer is 201 with entity, the claim's address, and changed. You may say where anyone lives, but only in a vault you may write; it answers 403 elsewhere. The claim records you as the one who said it. The same subject, place and kind again, in the same vault, is the same claim.
Read the place claims in a vault.
Send the vault's address as vault:
GET https://<name>.gilb.com/base/geo/place-claims?vault=<vault address>More about this
The answer is claims, a list; each has entity, placeUri, kind, subject, vaultId and author, who said it. It holds only the claims you may read. Any other option answers 400.
Deeper
Also asked:
How do places and positions work in the API? A place is a record in the place catalogue, found from words with /base/geo/bind. A thing's position is worked out from its frames with /base/geo/compose, and where someone lives or is is recorded with /base/geo/place-claims.
All four requests need a signed-in caller. With no token they answer 401, such as Sign in required to bind a place mention or Sign in required to read place claims. They take a plain Bearer token too: /lws, /files and many /base routes, such as /base/search, take it with no proof; the routes that sign in, trade tokens, register an app or run the AI chat do not.
A place claim's placeUri must start with https://geo.gilb.com/base/e/, and a claim cannot be kept in the catalogue vault. Today both refusals answer 500 InternalServerError, not 400; so does a place that holds a person fact such as a:occupant, and so do a frame walk that loops, and a record in the walk that also carries a:partOf or a:contains, since a frame is not a container. Nothing here changes the catalogue: a claim says who said that someone is at a place, and is kept in the claimant's vault.
The bind looks only in the catalogue, not in your own records, and it does not find places near a point; the answer on searching by text, attribute or place shows that.
The Developer Guide, GilbPlatform's guide for people who build apps on it, has no chapter on this yet; this answer is written from GilbPlatform's code.
Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/geo-bind.ts:27-31, :52-59 (body mention, minLength 1; pod refused by additionalProperties false), :65-82 (bearerFloorSurfacePrincipal; 401 Sign in required to bind a place mention; vault not a parameter); src/geo/bind-mention.ts:10 (BIND_CONFIDENCE_FLOOR 0.7), :20-27 (NFKD, lower case, accents dropped, non-letters as spaces), :29-43 (scores 1, 0.85, 0.55, 0.8, 0.45), :97-123 (catalogue vault GEO_VAULT_ID; read-authorized before scoring), :133-140 (too close: under 0.15 apart; miss below the floor; id null), :142-150 (id, aliases [the matched label], point from the geometry if a POINT, confidence, jurisdiction = a:memberOf or the region itself); src/geo/catalogue-types.ts:3-4 (GEO_VAULT_ID https://geo.gilb.com/base), :54-65 (a:frameParent, a:frameOffset tx ty tz or tx ty tz qw qx qy qz); src/routes/geo-compose.ts:31-39 (entity, target), :49-53 (401 Sign in required to compose a pose); src/geo/pose.ts:31-40 (offset forms), :138-149 (a:contains, a:partOf refused), :185-213 (16 hops; per-hop read authorization; stop at target, unreadable, missing, no parent; cycle refused; answer entity, target, pose, hops); src/routes/geo-place-claims.ts:73-89 (subject, placeUri, kind lives-at|present-at, claimantVault, claimantHost; additionalProperties false), :95-102 (GET vault; additionalProperties false), :116-132 (bearerFloorWriteRequirer; 401 Sign in required to write a place claim; 201 {entity, changed}), :134-158 (401 Sign in required to read place claims; claims filtered by authorizeReadIds); src/geo/place-claim.ts:64-67 (claim id from subject, place, kind), :69-73 (not in the catalogue vault), :88-90 (placeUri must start with https://geo.gilb.com/base/e/), :97-118 (claimant vault; agent = the requirer's principal), :145-189 (claims rows entity, placeUri, kind, subject, vaultId, author); src/geo/catalogue-write.ts:20-25 (CatalogueTypeError has no statusCode) with src/server/app.ts:244-256, :269 (so it is masked as 500 {error:InternalServerError}); src/write/ingest.ts:1415-1436 (agent bound). GilbVeda (public read, 2026-11-11): t:FrameParent (POSE ORIGIN ... IT IS NOT CONTAINMENT AND NOT MEMBERSHIP), t:FrameOffset ("literal \tx ty tz\ metres or \tx ty tz qw qx qy qz\"), t:PlaceClaim ("A claimant's assertion that they live-at or are present-at a catalogue place. Stored in the claimant pod."), t:ClaimKind, t:ClaimSubject, t:GeoPlace (all Suggested). Public reads, no token: 2026-11-11 https://geo.gilb.com/lws/vault/https%3A%2F%2Fgeo.gilb.com%2Fbase/records 200 (the catalogue lists with no token: anyone may read it); https://id.gilb.com/base/geo/place-claims?vault=https://geo.gilb.com/base 401 {error:Unauthorized,message:Sign in required to read place claims}. Shared with the GilbVeda page on space and time (a pose read only through what the asker may read; any signed-in person records, in a vault they may write, where someone lives or is; the record says who said it). Not checked on production: no POST sent; which host serves the catalogue for bind (geo.gilb.com chosen because it holds the catalogue). No Developer Guide chapter covers places.
For developers
curl
bind.sh
# Turn the words for a place into a catalogue place.
curl -s https://geo.gilb.com/base/geo/bind \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for POST https://geo.gilb.com/base/geo/bind>" \
-H "Content-Type: application/json" \
-d '{"mention":"<the words for a place>"}'
# 200: {"id":"<place address>","aliases":["<name>"],"point":"<WKT point>","confidence":1,"jurisdiction":"<region address>"}
# No sure match: {"id":null,"aliases":[],"point":null,"confidence":<under 0.7>,"jurisdiction":null}
curl
compose.sh
# Work out where a record sits, through its a:frameParent chain.
curl -s "https://<name>.gilb.com/base/geo/compose" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for POST https://<name>.gilb.com/base/geo/compose>" \
-H "Content-Type: application/json" \
-d '{"entity":"<record address>"}'
# 200: {"entity":"<record address>","target":"<the frame you named, or where the walk stopped>",
# "pose":{"x":0,"y":0,"z":0,"qw":1,"qx":0,"qy":0,"qz":0},"hops":<frames read>}
curl
place-claim.sh
# Record that someone lives at a place, in your own vault, then read the claims back.
curl -s "https://<name>.gilb.com/base/geo/place-claims" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for POST https://<name>.gilb.com/base/geo/place-claims>" \
-H "Content-Type: application/json" \
-d '{"subject":"<person address>","kind":"lives-at","placeUri":"<place address from bind>","claimantVault":"https://<name>.gilb.com/vault","claimantHost":"<name>.gilb.com"}'
curl -s -G "https://<name>.gilb.com/base/geo/place-claims" \
--data-urlencode "vault=https://<name>.gilb.com/vault" \
-H "Authorization: DPoP <token>" \
-H "DPoP: <a new proof for GET https://<name>.gilb.com/base/geo/place-claims>"
Checked against GilbApp d529620.