---
title: "`GET /places/search?q=…&lat=…&lon=…&limit=…&category=…`: full-text search over the caller's own places, proximity-biased when a focus point is given."
method: GET
path: "/places/search"
tags: ["places"]
---

# \`GET /places/search?q=…&lat=…&lon=…&limit=…&category=…\`: full-text search over the caller's own places, proximity-biased when a focus point is given.

`GET /places/search`

## Request

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

## Query parameters

- `q` string, required
- `lat` number, double
- `lon` number, double
- `limit` integer
- `category` string

## Response `200`

Ranked hits (empty when no dataset is stored)

- PlaceSearchResponse: Response for `GET /places/search`.
  - `count` integer, required: Number of results returned.
  - `query` string, required: The query text as interpreted.
  - `results` PlaceSearchHit[], required: Ranked hits, best first. Empty when no dataset is stored.
    - `distance_m` number, double, nullable: Haversine distance in metres from `lat`/`lon`, when given.
    - `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.
    - `score` number, float, required: Relevance score (text match × importance × proximity decay); larger is better, comparable only within one response.

## Other responses

- `400`: Missing `q` or a malformed parameter
- `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)