# 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:

| `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. |

```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
}
```

| 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](/docs/api-reference#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'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": {"...": "..."}
}
```

| 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=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](/docs/navigation-sessions#ending-at-a-door) 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](/docs/mcp):

- `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](/docs/mcp-tools).

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

- [Navigation sessions](/docs/navigation-sessions): turn-by-turn guidance on the gateway for voice and wearable clients
- [API reference](/docs/api-reference): geocoding, `GET /v1/places/in-view` and `POST /route`
- [MCP server](/docs/mcp): connect an assistant to these tools
- [Licensing](/docs/licensing): OpenStreetMap data and the ODbL
