Documentation menu
Place entrances
A place result gives one coordinate for a place, and for a station, a supermarket or an office block that point is often somewhere inside the building rather than at a way in. Someone walking there wants the door, a driver wants the door nearest the road, and a wheelchair user wants the step-free one.
MapMap can now return a place's doors and end a route at the right one:
- On place results.
include=entrancesonGET /geocode,GET /geocode/reverse,GET /geocode/retrieveandGET /v1/places/in-viewadds each place's entrances to the answer. - For one place.
GET /v1/places/{id}/entranceslists the entrances of one place by its id. - On a route.
POST /routeends at the best door for the costing when you name the place, and says which door it chose and why.
Every entrance served today is a door mapped in OpenStreetMap
(source: "osm") and tied to the place on evidence. None is estimated. The
response shape has room for estimated doors (source: "estimated"), but
MapMap does not produce any today.
What "tied to a place" means
A mapped door is only listed under a place when the map says the two
belong together. Each tie has a basis, strongest first:
basis | confidence | Evidence |
|---|---|---|
own_outline | high | The door is a point on the place's own building outline. |
stop_area | high | A public transport stop area lists the door and exactly one station. |
address_match | high | The door's own house number and street equal the place's, and it is on the building the place is in. |
sole_occupant | medium | The place is the only place inside a building that is not itself a named place, and the building's doors do not point elsewhere. |
confidence grades the tie between the door and the place. It says
nothing about whether the door is open, and it is not a positional
accuracy.
Where the map does not say which place a door belongs to, it is tied to none of them. A door two building outlines share, the doors of a shopping centre with many shops inside, a terrace mapped as one building, and a door on a different building are all refused rather than guessed.
So an empty list means no door is tied to the place, never that the
place has no entrance. Most places have no entrance node mapped at
all, and a building several places share is left untied unless its
addresses say which door is whose.
What we measured
Measured on 20 November 2026 against a UK OpenStreetMap extract of 30 October 2026, on London, Brighton, Leeds and Cambridge.
A 30-place check against the OpenStreetMap geometry (stations, hospitals, supermarkets and offices, half with doors mapped nearby and half without):
| Verdict | Places | Meaning |
|---|---|---|
| Right | 15 | The doors listed are the place's doors. |
| Right, none | 10 | No door is listed, and none is mapped on the place. |
| Partial | 2 | Some of the place's mapped doors are listed, not all. |
| Missed | 2 | The place has mapped doors and none is listed: a building the rules above refuse to guess about. |
| Wrong | 0 | A door listed that is not the place's. |
Coverage: the share of places with at least one tied door. This is how often you can expect an answer at all, and it varies most by kind of place:
| Places | With at least one tied door |
|---|---|
| London stations | 74 % |
| Hospitals | 0 to 8 % |
| Supermarkets | 6 to 21 % |
| Offices | 3 to 11 % |
Ranges are across the four towns. London stations are covered well because their OpenStreetMap stop areas list the station's entrances. Hospital sites are mapped as areas with the doors on the buildings inside them, and no rule ties a building's doors to the site, so hospitals rarely have an answer.
Entrances on place results: include=entrances
Add include=entrances to any of these:
| Endpoint | What is added |
|---|---|
GET /geocode | properties.entrances on every feature, and entrances_index on the collection. |
GET /geocode/reverse | The same. First-party index only: on a deployment that serves reverse geocoding through the Photon proxy it answers 501 reverse-filtering-not-enabled. |
GET /geocode/retrieve | properties.entrances on the feature, and entrances_index. |
GET /v1/places/in-view | id and entrances on every result, and entrances_index on the response. |
curl -fsS "$BASE/geocode/reverse?lat=51.53384&lon=-0.10738&kinds=poi&limit=2&include=entrances" \
-H "Authorization: Bearer $API_KEY"
{
"entrances_index": "loaded",
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [-0.1073789065082868, 51.53383992513021]},
"properties": {
"id": "osm:w119438298:poi",
"name": "Waitrose",
"categories": ["supermarket"],
"entrances": [
{"lon": -0.1070651, "lat": 51.533925200000006, "kind": "yes",
"wheelchair": null, "access": null, "door": null, "level": null,
"ref": null, "name": null, "osm_id": "osm:n1345642635",
"source": "osm", "confidence": "high", "basis": "own_outline"},
{"lon": -0.1073762, "lat": 51.5336653, "kind": "yes",
"wheelchair": null, "access": null, "door": null, "level": null,
"ref": null, "name": null, "osm_id": "osm:n1345642637",
"source": "osm", "confidence": "high", "basis": "own_outline"}
]
}
}
]
}
Trimmed to one feature and the fields that matter here; captured from a gateway running the UK extract above.
- Off by default. Without
include=entrancesevery response is exactly what it was before. entrancesis[]when the place is known and no door is tied to it, andnullfor a feature with no place id to look it up by.entrances_indexsays whether this deployment has entrance data:loaded,not-configured(none is installed, so everyentrancesisnullrather than an empty list that would read as "no doors") orfailed(the data is installed and did not load).- Any other
includevalue is a400that names it, so a typo is never a silent no-op.
Asking for entrances does not change what a request costs.
One place: GET /v1/places/{id}/entrances
id is a place id exactly as a place result reports it (properties.id,
for example osm:w119438298:poi).
curl -fsS "$BASE/v1/places/osm:w119438298:poi/entrances" \
-H "Authorization: Bearer $API_KEY"
{
"id": "osm:w119438298:poi",
"name": "Waitrose",
"lat": 51.53383992513021,
"lon": -0.1073789065082868,
"entrances": [
{"lon": -0.1070651, "lat": 51.533925200000006, "kind": "yes", "wheelchair": null,
"access": null, "door": null, "level": null, "ref": null, "name": null,
"osm_id": "osm:n1345642635", "source": "osm", "confidence": "high",
"basis": "own_outline"}
],
"entrances_index": "loaded",
"note": null
}
| Field | Meaning |
|---|---|
id | The place id you asked for. |
name, lat, lon | The place's own name and coordinate; null when this deployment has no place index. |
entrances | The tied doors (the entrance object below), [] when none is tied. |
entrances_index | loaded, not-configured or failed, as above. |
note | When entrances is empty, one sentence saying why: no door is mapped on the place, or the doors near it belong to a building other places share and their addresses do not say which. null otherwise. |
One call per request, and it needs a full key, like GET /v1/places/in-view
(see Browser keys).
| Status | When |
|---|---|
200 | The place is known. entrances may be empty. |
400 | An over-long id. |
401 | Missing or invalid API key. |
404 | No such place in this deployment's place index. |
429 | Quota or rate limit. |
501 | entrances-not-enabled: this deployment has no entrance data. Not billed, like every 501 that says a feature is not enabled. |
The entrance object
Every field is present on every entrance, null when the map does not say.
| Field | Meaning |
|---|---|
lon, lat | Where the door is, WGS84. |
kind | The OpenStreetMap entrance value: main, yes, entry, service, staircase, emergency, exit, home, garage or other. |
wheelchair | The mapped wheelchair value (yes, limited, no, ...). |
access | The mapped access value (yes, permissive, private, no, ...). |
door | The mapped door type (revolving, sliding, hinged, ...). |
level | The mapped floor level, as a string. |
ref | The door's mapped reference, such as an exit number. |
name | The door's mapped name. |
osm_id | The OpenStreetMap node, for example osm:n1345642635. |
source | osm for a door mapped in OpenStreetMap. estimated is reserved for doors MapMap infers; none is served today. |
confidence | high, medium or low: how sure the tie between door and place is (see the table at the top). |
basis | What tied them: own_outline, stop_area, address_match or sole_occupant. |
Ending a route at the door: POST /route
Name the place on the route request and the destination moves to the best of its doors before the route is computed. Either:
- put
place_id(a place result'sid) on the last location, or - add a top-level
arrive_at:"entrance"(the place is looked up at the destination coordinate), or an object{"place_id": "...", "entrance_kind": "main", "wheelchair": true}. Every key of the object is optional ("type": "entrance"may be sent too);entrance_kindis one ofmain,yes,entry,service,staircase,homeorgarage.
curl -fsS -X POST "$BASE/route" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"locations": [{"lat": 51.5136, "lon": -0.0800},
{"lat": 51.51214, "lon": -0.07877, "place_id": "osm:w56441629:poi"}],
"costing": "pedestrian"}'
The answer is the usual route plus an arrival block:
{
"arrival": {
"applied": true,
"place_id": "osm:w56441629:poi",
"entrance": {"lon": -0.07892210000000001, "lat": 51.512230900000006, "kind": "main",
"wheelchair": null, "access": "permissive", "door": "revolving",
"level": null, "ref": null, "name": null,
"osm_id": "osm:n4783747937", "source": "osm",
"confidence": "high", "basis": "own_outline"},
"reason": "main entrance, ranked first of 2 usable by kind then distance from the previous waypoint",
"eligible_entrances": 2,
"mapped_entrances": 2,
"moved_m": 14.6,
"original_destination": {"lat": 51.51214, "lon": -0.07877},
"entrances_index": "loaded"
},
"trip": {"...": "..."}
}
| Field | Meaning |
|---|---|
applied | true when the destination was moved to a door. |
place_id | The place whose doors were considered. |
entrance | The door chosen (the entrance object above). |
reason | Why this door, in one plain sentence. |
eligible_entrances, mapped_entrances | How many doors could be chosen, and how many are tied to the place in all. |
moved_m | How far the destination moved, in metres. |
original_destination | Where the route would have ended without this. |
entrances_index | loaded, not-configured or failed. |
How the door is chosen
- Never a door you cannot go in by. Emergency exits, exit-only doors
and doors mapped
access=nooraccess=privateare listed on the place but never chosen. - Public doors first. Service and garage doors are chosen only when
nothing public is tied to the place, or when
entrance_kindasks for one. - Step-free when asked. With
arrive_at.wheelchair: true, or a pedestrian route withcosting_options.pedestrian.type: "wheelchair", a door mappedwheelchair=yesis taken where one exists, and a door mappedwheelchair=nonever is. - Driving: the door nearest a road the vehicle can use. For car, lorry,
bus, motorcycle and scooter routes the routing engine places each door
against the road network and the nearest wins. If that lookup does not
answer, doors are ranked by kind and the
reasonsays so. - Walking and cycling: by kind, then distance from the previous waypoint.
It never fails the route
When no door can be chosen (the place has none tied, the deployment has no
entrance data, no place is found at the destination, or no door fits what
was asked for), the route is computed to the destination you sent and
arrival says why:
{"arrival": {"applied": false, "place_id": "osm:w119438298:poi",
"reason": "no entrance is mapped for this place",
"entrances_index": "loaded"}}
A malformed arrive_at, a place_id that is not a non-empty string, or a
place_id on the last location that disagrees with arrive_at.place_id is
a 400.
Ending a navigation session at the door
Navigation sessions take the
same arrive_at ("entrance" or the object form) on
POST /v1/navigation/sessions, choose the door the same way and answer
with the same arrival block. Every reroute heads for the same door.
Over MCP
On the MCP server:
place_entrancestakes a place id and returns its entrances, asGET /v1/places/{id}/entrancesdoes.nearby_places,places_in_viewandgeocodetakeinclude_entrances: trueand add each result's entrances.routetakesarrive_at: "entrance"(or the object form) to end at the best door of the destination place, with thearrivalblock in the answer.plan_daydoes not: its stops end where they are placed.start_navigationtakes the samearrive_atto end a navigation session at the door, with the samearrivalblock.
{"name": "nearby_places",
"arguments": {"lat": 51.5308, "lon": -0.1238, "category": "station",
"limit": 1, "include_entrances": true}}
An assistant passing an entrance on should say it is a mapped door, and read an empty list as "no door is mapped for this place", never as "it has no entrance". Every input and output is in the MCP tool reference.
In the SDKs
Web, @mapmap/maps. getPlaceEntrances wraps
GET /v1/places/{id}/entrances, and the place and geocode helpers take an
includeEntrances option. They are not in a published @mapmap/maps
release yet; until they are, add include=entrances to the URL yourself.
The web SDK's entrance surface, for reference: getPlaceEntrances(client, placeId)
takes GetPlaceEntrancesOptions and returns a PlaceEntrancesResult;
IncludeEntrancesOption is the includeEntrances flag the place helpers
share, and buildPlaceEntrancesUrl builds the request URL. Each door is a
PlaceEntrance typed with EntranceKind, EntranceSource (always osm
today), EntranceConfidence and EntranceBasis; EntrancesIndexStatus is
the deployment's entrances_index state. parseEntrance, parseEntrances
and parsePlaceEntrancesResponse read answers for clients that send their
own requests.
Generated API clients. GET /v1/places/{id}/entrances is the
get_place_entrances operation under the geocoding tag. With the
TypeScript client (@mapmap/api-client):
import { Configuration, GeocodingApi } from "@mapmap/api-client";
const geocoding = new GeocodingApi(
new Configuration({ basePath: "https://api.mapmap.ai", accessToken: "snk_..." }),
);
const place = await geocoding.getPlaceEntrances({ id: "osm:w119438298:poi" });
console.log(place.entrances);
With the Python client (mapmap-client):
import mapmap_client
from mapmap_client.api.geocoding_api import GeocodingApi
config = mapmap_client.Configuration(host="https://api.mapmap.ai", access_token="snk_...")
with mapmap_client.ApiClient(config) as api:
place = GeocodingApi(api).get_place_entrances("osm:w119438298:poi")
print(place)
Self-hosting
Entrance data is a side file the map factory writes beside the geocode
index for each territory. The gateway reads it from SN_ENTRANCES_PATH,
or from entrances.jsonl inside SN_GEOCODE_DIR. With neither, the
deployment has no entrance data: include=entrances answers with
entrances_index: "not-configured", GET /v1/places/{id}/entrances answers
501, and routes are computed to the destination as sent. The side file
follows the geocode index's place ids, so rebuild it with the index.
Next steps
- Navigation sessions: turn-by-turn guidance on the gateway for voice and wearable clients
- API reference: geocoding,
GET /v1/places/in-viewandPOST /route - MCP server: connect an assistant to these tools
- Licensing: OpenStreetMap data and the ODbL