# How do places work \(mentions, poses, claims\)?

Checked 2026-11-15 against GilbApp d5296208bbffa2ab70076e6194f5537c4be1ddf7.

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](http://support.gilb.com/help/how-do-i-use-the-sign-in-kit).

## Steps

1. Turn the words for a place into a place.

   Send mention, the words, as JSON, with the token and [a new DPoP proof](http://support.gilb.com/help/how-do-i-make-a-dpop-proof-for-each-request):
   POST https://geo.gilb.com/base/geo/bind

   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.
2. 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://&lt;name\>.gilb.com/base/geo/compose

   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.
3. Record where someone lives or is.

   Send subject, kind, placeUri, claimantVault and claimantHost as JSON to that vault's host:
   POST https://&lt;name\>.gilb.com/base/geo/place-claims

   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 &lt;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.
4. Read the place claims in a vault.

   Send the vault's address as vault:
   GET https://&lt;name\>.gilb.com/base/geo/place-claims?vault=&lt;vault address\>

   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](http://support.gilb.com/help/how-do-i-search-find-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

```curl
# 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

```curl
# 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

```curl
# 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>"
```
