--- title: "Quickly run a batch of geocoding queries against the search, structured search, or reverse endpoints." method: POST path: "/geocoding/v1/search/bulk" tags: ["Geocoding"] --- # Quickly run a batch of geocoding queries against the search, structured search, or reverse endpoints. `POST /geocoding/v1/search/bulk` The batch endpoint lets you specify many search, structured search, or reverse requests at once. Once received, all requests will be processed internally on our infrastructure, improving throughput when you need to do a lot of queries. ## Request body - object[] - `endpoint` '/v1/search' | '/v1/search/structured' | '/v1/reverse', required - `query` union, required - SearchQuery - `text` string — The place name (address, venue name, etc.) to search for. - `focus.point.lat` number, double — The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`. - `focus.point.lon` number, double — The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`. - `boundary.rect.min_lat` number, double — Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.max_lat` number, double — Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.min_lon` number, double — Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.max_lon` number, double — Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.circle.lat` number, double — The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`. - `boundary.circle.lon` number, double — The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`. - `boundary.circle.radius` number, double — The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified. - `boundary.country` string[] — A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format. - `boundary.gid` string — The GID of an area to limit the search to. - `layers` GeocodingLayer[] — A list of layers to limit the search to. - `sources` GeocodingSource[] — A list of sources to limit the search to. - `size` integer — The maximum number of results to return. - `lang` string — A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English. - SearchStructuredQuery - `address` string — A street name, optionally with a house number. - `neighbourhood` string — Varies by area, but has a locally specific meaning (NOT always an official administrative unit). - `borough` string — A unit within a city (not widely used, but present in places like NYC and Mexico City). - `locality` string — The city, village, town, etc. that the place/address is part of. - `county` string — Administrative divisions between localities and regions. Not commonly used as input to structured geocoding. - `region` string — Typically the first administrative division within a country. For example, a US state or a Canadian province. - `postalcode` string — A mail sorting code. - `country` string — A country code in ISO 3116-1 alpha-2 or alpha-3 format. - `focus.point.lat` number, double — The latitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lon`. - `focus.point.lon` number, double — The longitude of the point to focus the search on. This will bias results toward the focus point. Requires `focus.point.lat`. - `boundary.rect.min_lat` number, double — Defines the min latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.max_lat` number, double — Defines the max latitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.min_lon` number, double — Defines the min longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.rect.max_lon` number, double — Defines the max longitude component of a bounding box to limit the search to. Requires all other `boundary.rect` parameters to be specified. - `boundary.circle.lat` number, double — The latitude of the center of a circle to limit the search to. Requires `boundary.circle.lon`. - `boundary.circle.lon` number, double — The longitude of the center of a circle to limit the search to. Requires `boundary.circle.lat`. - `boundary.circle.radius` number, double — The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified. - `boundary.country` string[] — A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format. - `boundary.gid` string — The GID of an area to limit the search to. - `layers` GeocodingLayer[] — A list of layers to limit the search to. - `sources` GeocodingSource[] — A list of sources to limit the search to. - `size` integer — The maximum number of results to return. - `lang` string — A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English. - ReverseQuery - `point.lat` number, double — The latitude of the point at which to perform the search. - `point.lon` number, double — The longitude of the point at which to perform the search. - `boundary.circle.radius` number, double — The radius of the circle (in kilometers) to limit the search to. Defaults to 50km if unspecified. - `boundary.country` string[] — A list of country codes in ISO 3116-1 alpha-2 or alpha-3 format. - `boundary.gid` string — The GID of an area to limit the search to. - `layers` GeocodingLayer[] — A list of layers to limit the search to. - `sources` GeocodingSource[] — A list of sources to limit the search to. - `size` integer — The maximum number of results to return. - `lang` string — A BCP47 language tag which specifies a preference for localization of results. By default, results are in the default locale of the source data, but specifying a language will attempt to localize the results. Note that while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only the `language` portion, an ISO 639 code, will be considered. So `en-US` and `en-GB` will both be treated as English. ## Response `200` A JSON array of the individual query responses, each annotated with a status code. Individual requests may fail but this endpoint will still return all results. Responses will be in the same order as the input. - BulkSearchResponse[] - `status` integer, required - `response` 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. - `msg` string — An error message describing what went wrong (if the status is not 200). ## Other responses - `400` — Bad request; more details will be included --- [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)