Warning
This documentation covers a service that is currently in public beta. While we make a reasonable effort to ensure that things stay online, our beta services are not subject to the same availability guarantees of our other services. Additionally, beta services may not have the same global redundancy as our other services, so latency may be higher.
You will not be charged for beta access. If you continue using the service once it goes live, you will be charged as usual per the terms of our public pricing or your enterprise agreement.
Please send any feedback and issue reports to betafeedback@stadiamaps.com.
Search¶
Free
Starter
Standard
Professional
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.
Tip
A variety of other information such as phone numbers and Wikipedia links may also be available, depending on the
underlying data source. For example, if you search for 1600 Pennsylvania Avenue NW, Washington, DC, USA
you
can learn that The White House is located at (38.897682, -77.036567)
, has a Wikipedia page named
en:White House
, and has a postal code of 20500
.
The only required parameter is text
, but the results can be easily tuned to meet your needs.
- Bias results with the
focus.point
parameters - Ignore anything outside a bounding box, circle, or country using the
boundary
parameters - Limit the data sources searched using the
sources
parameter - Limit the layers searched using the
layers
parameter
Endpoint: https://api.stadiamaps.com/geocoding/v1/search
Query String Parameters¶
Parameter | Type | Required | Description | Default | Example |
---|---|---|---|---|---|
text |
string | yes | The place name (address, venue name, etc.) to search for. | none | Union Square |
focus.point.lat |
float | no | The latitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lon |
none | 48.581755 |
focus.point.lon |
float | no | The longitude of the point to focus the search on. This will bias results toward the focus point. Requires focus.point.lat |
none | 7.745843 |
boundary.rect.min_lon |
float | no | Defines the min longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified. |
none | 139.2794 |
boundary.rect.max_lon |
float | no | Defines the max longitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified. |
none | 140.1471 |
boundary.rect.min_lat |
float | no | Defines the min latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified. |
none | 35.53308 |
boundary.rect.max_lat |
float | no | Defines the max latitude component of a bounding box to limit the search to. Requires all other boundary.rect parameters to be specified. |
none | 35.81346 |
boundary.circle.lat |
float | no | The latitude of the center of a circle to limit the search to. Requires boundary.circle.lon . |
none | 43.818156 |
boundary.circle.lon |
float | no | The latitude of the center of a circle to limit the search to. Requires boundary.circle.lat . |
none | -79.186484 |
boundary.circle.radius |
float | no | Tho radius of the circle (in kilometers) to limit the search to. Requires the other boundary.circle parameters to take effect. |
50 |
35 |
layers |
comma-delimited string array | no | A list of layers, to limit the search to. | all layers | address,venue |
sources |
comma-delimited string array | no | A list of sources, to limit the search to. | all sources | openstreetmap,wof |
boundary.country |
comma-delimited string array | no | A list of countries to limit the search to. | none | GBR,FRA |
boundary.gid |
Pelias GID | no | The Pelias GID of a region to limit the search to. | none | whosonfirst:locality:101748355 |
size |
integer | no | The maximum number of results to return. | 10 |
3 |
Notes and tips¶
- Be sure to read Determining Result Quality and our best practices.
- If possible, use the structured search endpoint instead for postal addresses.
Response format¶
All geocoding, autocomplete, and search endpoints share a common response format. See the response format documentation for details.