---
title: "Look up addresses, businesses and places"
method: GET
path: "/places/lookup"
tags: ["discovery"]
---

# Look up addresses, businesses and places

`GET /places/lookup`

## Request

- Base URL: `https://api.mapsource.io`
- URL: `https://api.mapsource.io/places/lookup`
- Auth: HTTP bearer

Local OSM address/name lookup for map search and routing destination pickers. Supports business categories, partial names, accent normalization and typo matching. Coordinates bias ranking; bounded=true is required to restrict results to bbox. When the global index is unavailable, coverage identifies the regional Overpass and place-name-index fallback. Included in every subscription plan: one successful lookup counts as one request, plus an interpreter request if regional Overpass fallback is used. Search index freshness is independent of the Overpass dataset; read coverage.dataTimestamp.

When to use: Find an address, business, brand, landmark, street or populated place. Use a location qualifier such as Starbucks in Portland to search away from the map focus.

When not to use: Use discoverPlaces to enumerate businesses in a viewport or travel-time region. Ranking scores are not probabilities; bestMatchId is null for ambiguous matches. House numbers are never substituted.

## Query parameters

- `q` string, required
- `lat` number
- `lon` number
- `limit` integer
- `language` string
- `types` string
- `category` string
- `countrycodes` string
- `bbox` string
- `bounded` boolean

## Response `200`

Look up addresses, businesses and places

- object
  - `schema` 'mapsource-lookup.v1'
  - `query` string
  - `bestMatchId` string, nullable
  - `ambiguous` boolean
  - `results` object[]
    - `id` string
    - `kind` 'address' | 'business' | 'landmark' | 'street' | 'place'
    - `name` string
    - `displayName` string
    - `coordinate` object
      - `lat` number
      - `lon` number
    - `distanceMeters` number
    - `category` string
    - `address` object: Source-provided fields only. Missing houseNumber, street, city and other address fields are omitted.
    - `match` object
      - `type` 'exact' | 'prefix' | 'partial' | 'fuzzy' | 'category' | 'indexed': Text match classification. Indexed means the search index resolved the query using fields or aliases not present in the displayed name.
      - `score` number: Ranking score, not a probability. Global-index results preserve engine order and use reciprocal source rank. Regional results use lexical relevance with soft proximity. Scores are not comparable across queries or coverage modes.
    - `sources` object[]
      - `dataset` string
      - `type` string
      - `id` string
  - `warnings` string[]
  - `coverage` object: Global-index or regional coverage; regional candidate truncation is explicit. A regional fallback may make one additional quota-counted interpreter call.

## Other responses

- `400`: Error with a stable machine code.
- `401`: Error with a stable machine code.
- `429`: Error with a stable machine code.
- `500`: Error with a stable machine code.

---

[API](https://skmtc.dev/mapsource/apis/mapsource-overpass-api.md) · [All operations](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapsource/apis/mapsource-overpass-api/revisions/8af8c2769e7b?raw)