Geocoding API Documentation
The Geocoding API provides forward and reverse geocoding search based on data by OpenStreetMap contributors.
By using this API you must adhere to the OpenStreetMap attribution requirements as stated here.
The Geocoding API relies on a redundant infrastructure of geocoder nodes powered by the Nominatim software with edge servers for fast delivery of results.
A free tier is available for private hobby use (e.g. private websites without ads and tracking scripts).
For business needs, several plans are available.
All plans are eligble to use the standard geocoding endpoints for forward and reverse geocoding.
Visit www.geocodingapi.net to sign up for an api key and subscribe to a plan.
Endpoints
/v1/search- GeocodingSearch: Free-form forward geocoding search./v1/forward- ForwardGeocoding: Structured forward geocoding./v1/reverse- ReverseGeocoding: Reverse geocoding.
GeocodingSearch /v1/search
Endpoint: https://forward-reverse-geocoding.p.rapidapi.com/v1/search?query
A free-form forwarding geocoding search. (For a structured forward geocoding search, use the alternative ForwardGeocoding endpoint.)
Query param options
| param | required | value options | notes |
|---|---|---|---|
| q | required | free-form search query | |
| format | [json,jsonv2,xml,geojson,geocodejson] | default: json | |
| addressdetails | [0,1] | default: 0 | |
| namedetails | [0,1] | default: 0 | |
| extratags | [0,1] | default: 0 | |
| accept-language | two letter or four letter language code | e.g. "en" or "en-GB" | |
| json_callback | callback function | for json format | |
| polygon_geojson | [0,1] | default: 0 | |
| polygon_kml | [0,1] | default: 0 | |
| polygon_svg | [0,1] | default: 0 | |
| polygon_text | [0,1] | default: 0 | |
| countrycodes | (two letter country code array) | restrict results to those countries, must use the ISO 3166-1 alpha-2 code | |
| viewbox | x1,y1,x2,y2 | restrict search to viewing box (use in combination with bounded=1) | |
| bounded | [0,1] | default: 0 - use this in combination with viewbox coordinates | |
| polygon_threshold | default: 0.0 | ||
| limit | [1...20] | limit the number of results, default: 1 |
ForwardGeocoding v1/forward
Endpoint: https://forward-reverse-geocoding.p.rapidapi.com/v1/forward?query
A structured forward geocoding search. Use this for a better structured search using street, housenumber, city, county and country as input. The ForwardGeocoding search endpoint can also be used for address verification or address completion, e.g. to find the postcode for a street and city. Set addressdetails to 1 to use this function for address completion or postcode search.
For a free-form forward geocoding search, use the GeocodingSearch endpoint.
query param options
| param | required | value options | notes |
|---|---|---|---|
| street | at least one of street, city, postcode, county or country is required | (housenumber) street | if using a housenumber, prefix it |
| postalcode | at least one of street, city, postalcode, county, state or country is required | ||
| city | at least one of street, city, postalcode, county, state or country is required | ||
| county | at least one of street, city, postalcode, county, state or country is required | ||
| state | at least one of street, city, postalcode, county, state or country is required | ||
| country | at least one of street, city, postalcode, county, state or country is required | ||
| format | [json,jsonv2,xml,geojson,geocodejson] | default: json | |
| addressdetails | [0,1] | default: 0 | |
| namedetails | [0,1] | default: 0 | |
| extratags | [0,1] | default: 0 | |
| accept-language | two letter or four letter language code | e.g. "en" or "en-GB" | |
| json_callback | callback function | for json format | |
| polygon_geojson | [0,1] | default: 0 | |
| polygon_kml | [0,1] | default: 0 | |
| polygon_svg | [0,1] | default: 0 | |
| polygon_text | [0,1] | default: 0 | |
| countrycodes | (two letter country code array) | restrict results to those countries, must use the ISO 3166-1 alpha-2 code | |
| viewbox | x1,y1,x2,y2 | restrict search to viewing box (use in combination with bounded=1) | |
| bounded | [0,1] | default: 0 - use this in combination with viewbox coordinates | |
| polygon_threshold | default: 0.0 | ||
| limit | [1...20] | limit the number of results, default: 1 |
ReverseGeocoding v1/reverse
Endpoint: https://forward-reverse-geocoding.p.rapidapi.com/v1/reverse?query
Find an address or a place for a geography coordinate.
query param options
| param | required | value options | notes |
|---|---|---|---|
| lat | required | ||
| lon | required | ||
| zoom | recommended | [0...18] | see extra zoom table, set the zoom to define the administrative area you want as a result |
| format | [json,jsonv2,xml,geojson,geocodejson] | default: json | |
| addressdetails | [0,1] | default: 0 | |
| namedetails | [0,1] | default: 0 | |
| extratags | [0,1] | default: 0 | |
| accept-language | two letter or four letter language code | e.g. "en" or "en-GB" | |
| json_callback | callback function | for json format | |
| polygon_geojson | [0,1] | default: 0 | |
| polygon_kml | [0,1] | default: 0 | |
| polygon_svg | [0,1] | default: 0 | |
| polygon_text | [0,1] | default: 0 | |
| polygon_threshold | default: 0.0 | ||
| limit | [1...20] | limit the number of results, default: 1 |
Zoom values for reverse geocoding endpoint
| zoom | returned detail |
|---|---|
| 3 | country |
| 5 | state |
| 8 | county |
| 10 | city |
| 12 | town |
| 14 | suburb |
| 16 | major street |
| 17 | major or minor street |
| 18 | building |