Skip to content
Documentation menu
docs / entrances · raw .md

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=entrances on GET /geocode, GET /geocode/reverse, GET /geocode/retrieve and GET /v1/places/in-view adds each place's entrances to the answer.
  • For one place. GET /v1/places/{id}/entrances lists the entrances of one place by its id.
  • On a route. POST /route ends 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:

basisconfidenceEvidence
own_outlinehighThe door is a point on the place's own building outline.
stop_areahighA public transport stop area lists the door and exactly one station.
address_matchhighThe door's own house number and street equal the place's, and it is on the building the place is in.
sole_occupantmediumThe 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):

VerdictPlacesMeaning
Right15The doors listed are the place's doors.
Right, none10No door is listed, and none is mapped on the place.
Partial2Some of the place's mapped doors are listed, not all.
Missed2The place has mapped doors and none is listed: a building the rules above refuse to guess about.
Wrong0A 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:

PlacesWith at least one tied door
London stations74 %
Hospitals0 to 8 %
Supermarkets6 to 21 %
Offices3 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:

EndpointWhat is added
GET /geocodeproperties.entrances on every feature, and entrances_index on the collection.
GET /geocode/reverseThe 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/retrieveproperties.entrances on the feature, and entrances_index.
GET /v1/places/in-viewid and entrances on every result, and entrances_index on the response.
bash
curl -fsS "$BASE/geocode/reverse?lat=51.53384&lon=-0.10738&kinds=poi&limit=2&include=entrances" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "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=entrances every response is exactly what it was before.
  • entrances is [] when the place is known and no door is tied to it, and null for a feature with no place id to look it up by.
  • entrances_index says whether this deployment has entrance data: loaded, not-configured (none is installed, so every entrances is null rather than an empty list that would read as "no doors") or failed (the data is installed and did not load).
  • Any other include value is a 400 that 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).

bash
curl -fsS "$BASE/v1/places/osm:w119438298:poi/entrances" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "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
}
FieldMeaning
idThe place id you asked for.
name, lat, lonThe place's own name and coordinate; null when this deployment has no place index.
entrancesThe tied doors (the entrance object below), [] when none is tied.
entrances_indexloaded, not-configured or failed, as above.
noteWhen 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).

StatusWhen
200The place is known. entrances may be empty.
400An over-long id.
401Missing or invalid API key.
404No such place in this deployment's place index.
429Quota or rate limit.
501entrances-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.

FieldMeaning
lon, latWhere the door is, WGS84.
kindThe OpenStreetMap entrance value: main, yes, entry, service, staircase, emergency, exit, home, garage or other.
wheelchairThe mapped wheelchair value (yes, limited, no, ...).
accessThe mapped access value (yes, permissive, private, no, ...).
doorThe mapped door type (revolving, sliding, hinged, ...).
levelThe mapped floor level, as a string.
refThe door's mapped reference, such as an exit number.
nameThe door's mapped name.
osm_idThe OpenStreetMap node, for example osm:n1345642635.
sourceosm for a door mapped in OpenStreetMap. estimated is reserved for doors MapMap infers; none is served today.
confidencehigh, medium or low: how sure the tie between door and place is (see the table at the top).
basisWhat 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's id) 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_kind is one of main, yes, entry, service, staircase, home or garage.
bash
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:

json
{
  "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": {"...": "..."}
}
FieldMeaning
appliedtrue when the destination was moved to a door.
place_idThe place whose doors were considered.
entranceThe door chosen (the entrance object above).
reasonWhy this door, in one plain sentence.
eligible_entrances, mapped_entrancesHow many doors could be chosen, and how many are tied to the place in all.
moved_mHow far the destination moved, in metres.
original_destinationWhere the route would have ended without this.
entrances_indexloaded, 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=no or access=private are 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_kind asks for one.
  • Step-free when asked. With arrive_at.wheelchair: true, or a pedestrian route with costing_options.pedestrian.type: "wheelchair", a door mapped wheelchair=yes is taken where one exists, and a door mapped wheelchair=no never 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 reason says 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:

json
{"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_entrances takes a place id and returns its entrances, as GET /v1/places/{id}/entrances does.
  • nearby_places, places_in_view and geocode take include_entrances: true and add each result's entrances.
  • route takes arrive_at: "entrance" (or the object form) to end at the best door of the destination place, with the arrival block in the answer. plan_day does not: its stops end where they are placed.
  • start_navigation takes the same arrive_at to end a navigation session at the door, with the same arrival block.
json
{"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):

ts
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):

python
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