---
title: "Discover matching places"
method: GET
path: "/discover"
tags: ["Places"]
---

# Discover matching places

`GET /discover`

## Query parameters

- `key` string, 32 character alphanumeric string, required
- `q` string, required
- `at` string, latitude,longitude
- `in` string
- `limit` integer
- `lang` string

## Response `200`

- object
  - `items` object[] — The results are presented as a JSON list of candidates in ranked order (most-likely to least-likely) based on the matched location criteria.
    - `title` string — The localized display name of this result item.
    - `id` string — The unique identifier for the result item.
    - `address` Address — Postal address of the result item.
      - `label` string — Assembled address value built out of the address components according to the regional postal rules. These are the same rules for all endpoints. It may not include all the input terms.
      - `countryCode` string — A three-letter country code.
      - `countryName` string — The localised country name.
      - `stateCode` string — A country specific state code or state name abbreviation. For example, in the United States it is the two letter state abbreviation: "CA" for California.
      - `state` string — The state division of a country.
      - `county` string — A division of a state; typically, a secondary-level administrative division of a country or equivalent.
      - `city` string — The name of the primary locality of the place.
      - `district` string — A division of city; typically an administrative unit within a larger city or a customary name of a city's neighborhood.
      - `street` string — Name of street of the returned place, if available.
      - `postalCode` string — An alphanumeric string included in a postal address to facilitate mail sorting, such as post code, postcode, or ZIP code.
      - `houseNumber` string — House number of the returned place, if available.
    - `scoring` Scoring — Score of the result. A higher score indicates a closer match.
      - `queryScore` number — A score, out of 1, indicating how closely the result matches with the provided query q .
      - `fieldScore` object — A breakdown of how closely individual field of the result matched with the provided query q.
    - `position` Position — Returns the location coordinates of the result.
      - `lat` string — The latitude of the searched place.
      - `lng` string — The longitude of the searched place.
    - `access` Access — An array returning the location coordinates of all the access points of the search result.
      - `lat` number — The latitude of the access point of the search result.
      - `lng` number — The longitude of the access point of the search result.
    - `distance` integer — The distance "as the crow flies" from the search center to this result item in meters.
    - `mapView` MapView — The bounding box enclosing the geometric shape (area or line) that an individual result covers. place typed results have no mapView.
      - `west` string — Longitude of the western-side of the box.
      - `south` string — Longitude of the southern-side of the box.
      - `east` string — Longitude of the eastern-side of the box.
      - `north` string — Longitude of the northern-side of the box.
    - `categories` Categories[] — The list of categories assigned to this place.
      - `id` string — Identifier number for an associated category.
      - `name` string — Name of the place category in the result item language.
      - `primary` string — Whether or not it is a primary category. This field is visible only when the value is 'true'.
    - `contacts` Contacts[] — Contact information like phone, email or website.
      - `phone` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
      - `mobile` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
      - `tollFree` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
      - `fax` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
      - `www` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
      - `email` ContactObject[]
        - `label` string — Optional label for the contact string, such as "Customer Service" or "Pharmacy Fax".
        - `value` string — Contact information, as specified by the contact type.
        - `categories` object[] — The list of place categories this contact refers to.
          - `id` string — Identifier number for an associated category. For example: "900-9300-0000"
    - `openingHours` object — Returns the operating hours of the place, if available.
      - `timeRanges` object[] — A collection of attributes with details about the opening and closing hours for each day of the week.
        - `startTime` object — Returns the open time details.
          - `date` string — The date to which the subsequent open time details belong to.
          - `hour` integer — The hour of the day when the place opens.
          - `minute` integer — The minute of the hour when the place opens.
        - `endTime` object — Returns the closing time details.
          - `date` string — The date to which the subsequent closing time details belong to.
          - `hour` integer — The hour of the day when the place closes.
          - `minute` integer — The minute of the hour when the place closes.

---

[API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/versions/b647f1808dda/schema)