---
title: "Search for location and other info using a place name or address (forward geocoding)."
method: GET
path: "/geocoding/v1/search"
tags: ["Geocoding"]
---

# Search for location and other info using a place name or address (forward geocoding).

`GET /geocoding/v1/search`

The search endpoint lets you search for addresses, points of interest, and administrative areas. This is most commonly used for forward geocoding applications where you need to find the geographic coordinates of an address.

## Query parameters

- `text` string, required
- `focus.point.lat` number, double
- `focus.point.lon` number, double
- `boundary.rect.min_lat` number, double
- `boundary.rect.max_lat` number, double
- `boundary.rect.min_lon` number, double
- `boundary.rect.max_lon` number, double
- `boundary.circle.lat` number, double
- `boundary.circle.lon` number, double
- `boundary.circle.radius` number, double
- `boundary.country` string[]
- `boundary.gid` string
- `layers` GeocodingLayer[]
- `sources` GeocodingSource[]
- `size` integer
- `lang` string

## Response `200`

A GeoJSON collection of search results.

- GeocodeResponse
  - `geocoding` GeocodingObject, required
    - `attribution` string, uri — A URL containing attribution information. If you are not using Stadia Maps and our standard attribution already for your basemaps, you must include this attribution link somewhere in your website/app.
    - `query` object — Technical details of the query. This is most useful for debugging during development. See the full example for the list of properties; these should be self-explanatory, so we don't enumerate them in the spec.
    - `warnings` string[] — An array of non-critical warnings. This is normally for informational/debugging purposes and not a serious problem.
    - `errors` string[] — An array of more serious errors (for example, omitting a required parameter). Don’t ignore these.
  - `bbox` number[] — An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
  - `features` GeocodingGeoJSONFeature[], required
    - `type` 'Feature', required
    - `geometry` GeoJSONPoint, required
      - `type` 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon', required
      - `coordinates` number[], required
    - `properties` GeocodingGeoJSONProperties
      - `gid` string — A scoped GID for this result. This can be passed to the place endpoint. Note that these are not always stable long-term.
      - `source_id` string — An ID referencing the original data source (specified via source) for the result. These IDs are specific to the source that they originated from. For example, in the case of OSM, these typically look like way/123 or point/123.
      - `label` string — A full, human-readable label. However, you may not necessarily want to use this; be sure to read the docs for name, locality, and region before making a decision. This field is mostly localized. The order of components is generally locally correct (ex: for an address in South Korea, the house number appears after the street name). However, components will use a request language equivalent if one exists (ex: Seoul instead of 서울 if lang=en).
      - `layer` string — The data layer containing the place (e.g. "address" or "venue").
      - `source` string — The ID of the data source that the result came from.
      - `name` string — The name of the place, the street address including house number, or label of similar relevance. If your app is localized to a specific region, you may get better display results by combining name, locality OR region (or neither?), and postal code together in the local format. Experiment with what works best for your use case.
      - `accuracy` 'point' | 'centroid' — The accuracy of the geographic coordinates in the result. This value is a property of the result itself and won't change based on the query. A point result means that the record can reasonably be represented by a single geographic point. Addresses, venues, or interpolated addresses usually have point accuracy. Larger areas, such as a city or country, cannot be represented by a single point, so a centroid is given instead.
      - `addendum` object — Optional additional information from the underlying data source (ex: OSM). This includes select fields. The most useful fields are mapped in the definition here, but others may be available.
        - `osm` object
          - `website` string, uri
          - `wikipedia` string
          - `wikidata` string
          - `phone` string
      - `continent` string
      - `continent_gid` string
      - `country` string
      - `country_a` string — The ISO 3166-1 alpha-3 code for the country the place is located in.
      - `country_code` string — The ISO 3166-1 alpha-2 code for the country the place is located in.
      - `country_gid` string
      - `neighbourhood` string
      - `neighbourhood_gid` string
      - `borough` string
      - `borough_gid` string
      - `postalcode` string
      - `street` string
      - `housenumber` string
      - `locality` string — The city, village, town, etc. that the place / address is part of. Note that values may not always match postal or local conventions perfectly.
      - `locality_gid` string
      - `county` string — Administrative divisions between localities and regions. Useful for disambiguating nearby results with similar names.
      - `county_gid` string
      - `region` string — Typically the first administrative division within a country. For example, a US state or a Canadian province.
      - `region_a` string — The abbreviation for the region (e.g. PA for the US state of Pennsylvania).
      - `region_gid` string
      - `localadmin` string — In many countries, this is the lowest level of government. Sometimes interchangeable with locality.
      - `localadmin_gid` string
      - `match_type` 'exact' | 'interpolated' | 'fallback' — For search and structured search results, the type of match.
      - `confidence` number, double — The level of confidence that the result matches what the user searched for. Only available on forward geocoding endpoints.
    - `bbox` number[] — An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.

## Other responses

- `400` — Bad request

---

[API](https://skmtc.net/stadiamaps/apis/stadia-maps-geospatial-apis.md) · [All operations](https://skmtc.net/stadiamaps/apis/stadia-maps-geospatial-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stadiamaps/stadia-maps-geospatial-apis/versions/99e0701a73aa/schema)