---
title: "Find businesses and POIs in a region"
method: POST
path: "/places/discover"
tags: ["discovery"]
---

# Find businesses and POIs in a region

`POST /places/discover`

## Request

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

Select OSM shops, offices, amenities and visitor facilities inside a viewport, polygon or travel-time region. Uses the local Overpass database, polygon filtering and, optionally, Valhalla. No geocoder index is required. Each internal Overpass, isochrone or matrix request consumes its normal quota; the composition adds no separate request charge.

When to use: Find coffee within a 15-minute drive, list businesses in a map viewport, or filter POIs by an existing isochrone. Paginate bounded results; narrow the area when coverage.truncated is true.

When not to use: Use lookupPlaces for ranked address/name suggestions. Discovery uses feature centers, not full-geometry intersections. It does not guarantee a complete real-world business directory: only mapped OSM records are available. Travel-time ranking compares at most the 25 nearest candidates.

## Request body

- object
  - `q` string: Optional business name or brand filter.
  - `category` string: Optional category alias, such as coffee, pharmacy, restaurants, hotels or shops.
  - `bbox` union: west,south,east,north (a four-number array is also accepted). Maximum extent: one degree per axis. Supply exactly one of bbox, region or minutes.
    - string
    - number[]
  - `region` union: GeoJSON Polygon, MultiPolygon, polygon Feature/FeatureCollection, or an owned result-handle ID. Closed rings required; holes excluded. Maximum encoded coordinates: 100 KB.
    - string
    - object
  - `minutes` integer: Generate a reachable region from lat/lon.
  - `lat` number: Latitude in decimal degrees.
  - `lon` number: Longitude in decimal degrees.
  - `costing` 'auto' | 'bicycle' | 'pedestrian' | 'truck': Travel mode for isochrone and matrix requests.
  - `rankBy` 'distance' | 'travel_time': distance sorts from lat/lon or the region center. travel_time requires lat/lon, limit <=25 and offset=0; unreachable times remain null.
  - `limit` integer: Page size.
  - `offset` integer: Offset into the bounded candidate results; re-query after dataset updates may change ordering.
  - `language` string: Preferred source name language.

## Response `200`

Find businesses and POIs in a region

- object
  - `schema` 'mapsource-discovery.v1'
  - `query` string
  - `results` unknown[]: Lookup-format records with string OSM IDs and travelTimeSeconds (null unless measured).
    - unknown
  - `region` object: Search polygon.
  - `pagination` object
    - `offset` integer
    - `limit` integer
    - `matched` integer
    - `nextOffset` integer, nullable
  - `coverage` object
    - `candidateLimit` 2000
    - `truncated` boolean
    - `geometryRule` string
    - `bbox` unknown[]
      - unknown
  - `ranking` object
  - `warnings` string[]
  - `meta` object
    - `requestId` string
    - `computeMs` integer
    - `requestedAt` string, date-time
    - `sources` object[]
      - `dataset` string
      - `observedAt` string, nullable
      - `license` string
    - `freshness` object, nullable
    - `licenses` string[]
    - `attribution` string[]

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