---
title: "`GET /places/nearest?lat=…&lon=…&limit=…`: the caller's places nearest to a point, by haversine distance (no text query, no index)."
method: GET
path: "/places/nearest"
tags: ["places"]
---

# \`GET /places/nearest?lat=…&lon=…&limit=…\`: the caller's places nearest to a point, by haversine distance (no text query, no index).

`GET /places/nearest`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/places/nearest`
- Auth: one of:
  - HTTP bearer
  - API key in query parameter `api_key`

## Query parameters

- `lat` number, double, required
- `lon` number, double, required
- `limit` integer

## Response `200`

Places ordered nearest first (empty when no dataset is stored)

- PlaceNearestResponse: Response for `GET /places/nearest`.
  - `count` integer, required: Number of results returned.
  - `results` PlaceNearestHit[], required: Hits ordered nearest first. Empty when no dataset is stored.
    - `distance_m` number, double, required: Haversine distance in metres from the query point.
    - `place` Place, required: One customer place, as uploaded and as returned.
      - `alt_names` string[]: Alternative names (abbreviations, old names); at most 8.
      - `categories` string[]: Categories used by the `category` search filter (e.g. `"supermarket"`); at most 16, matched case-insensitively.
      - `country_code` string, nullable: ISO 3166-1 alpha-2 country code, e.g. `"GB"`.
      - `id` string, required: Caller-chosen stable identifier, unique within the dataset (1–128 bytes), e.g. `"store-042"`.
      - `importance` number, float, nullable: Rank boost in [0, 1]; larger means more prominent. Defaults to 0.5.
      - `lat` number, double, required: Latitude in decimal degrees (WGS84), within [-90, 90].
      - `locality` string, nullable: Town or city, for display and search context.
      - `lon` number, double, required: Longitude in decimal degrees (WGS84), within [-180, 180].
      - `name` string, required: Primary display name (1–200 bytes), e.g. `"MyBrand Croydon"`.
      - `postcode` string, nullable: Postcode, formatted as displayed.
      - `properties` unknown
      - `region` string, nullable: County / region, for display and search context.
      - `street` string, nullable: Street, for display and search context.

## Other responses

- `400`: Missing or malformed `lat`/`lon`
- `401`: Missing or invalid API key
- `404`: Customer places not configured on this gateway

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)