+ What is Geocoding?

Geocoding is the process of converting a human-readable address into a pair of latitude and longitude coordinates, which are necessary to "plot" the address on the map. Reverse Geocoding is the opposite, i.e. converting a pair of lat/long coordinates into an address.

+ About This Geocoding API Service

This geocoding API is provided to the public, for free, as a community service by Map Maker (My Maps Inc), a web-based GIS & map making tool that uses the Google Maps API.

In listening to our customers, we recognized that not everybody requires commercial-grade geocoding accuracy and that for many it is cost prohibitive. For example, the Google Maps API currently charges $7 per 1000 geocode lookups. If you have millions of locations to geocode, that is clearly cost prohibitive.

So, we searched for a way to allow anyone to perform geocode lookups, for free! We found open-source software from OpenStreetMap (OSM) and Nominatim. These packages can be used by anyone to create a geocoding API, however setting them up requires a significant amount of experience (Linux server admin), time (3+ days just to import OSM data), and money (needs powerful servers!).

But don't worry... we have endured this stress and expense on your behalf, so that you can get on with your task at hand: geocoding your data and creating great maps!

+ How To Geocode / Search?

Please see the instructions below for both forward and reverse geocoding.

Forward Geocoding (convert address to coordinates):

To "free form" search for an address, you can pass the address string using the q parameter to the /search endpoint, e.g.:

https://geocode.maps.co/search?q=555+5th+Ave+New+York+NY+10017+US

Or you can search by name, e.g. for the Statue of Liberty:

https://geocode.maps.co/search?q=Statue+of+Liberty+NY+US

However, you can also reverse geocode by providing the following parameters:

  • street=<housenumber> <streetname>
  • city=<city>
  • county=<county>
  • state=<state>
  • country=<country>
  • postalcode=<postalcode>

For example:

https://geocode.maps.co/search?street=555+5th+Ave&city=New+York&state=NY&postalcode=10017&country=US

Reverse Geocoding (convert coordinates to address / place):

To reverse geocode, provide both the lat and lon parameters to the /reverse endpoint, e.g:

https://geocode.maps.co/reverse?lat=40.7558017&lon=-73.9787414

NOTE: Our API endpoints return JSON data by default. To return data in a different format, you can append "&format={format}", where {format} is one of the following: xml, json, jsonv2, geojson, geocodejson. Please remember to substitute {address}, {latitude} and {longitude} in the URLs above with your URL-endoded values.

+ API Limitations / Rate Throttling

Updated November 24 2023: To ensure reliable service availability for all users, the current API limit is 1 request per second. Unfortunately, some users are attempting to circumvent rate limits by querying from multiple IP addresses and subnets. In cases where we identify this type of abuse, we may block entire ISPs from accessing this service. Please do not abuse this free service and ruin it for everyone else!

If you need high volume geocoding... Please contact us for pricing details.

If your application exceeds the request limit, requests will be rejected with an HTTP 429 response. Upon receiving an HTTP 429 response, please throttle your application's rate of requests, e.g., by implementing a 1-second pause after each request.

Since HTTP 429 responses will not contain any geocoding results, such queries will need to be performed again after a delay.

During periods of extremely high traffic loads the server may refuse to process your request and instead respond with an HTTP 503. In addition to the HTTP 503, the server may issue a "Retry-After" header indicating the number of seconds to wait before attempting the API query again.

We reserve the right to block clients deemed to be abusing the service, e.g., clients making excessive repeated/duplicate requests (please cache API results), ignoring HTTP response codes that indicate your client should moderate request rates, flooding the API service with requests that consume too many server resources, etc. Blocked clients will receive an HTTP 403 response. If your client receives an HTTP 403, please contact us at the email address above so that we can work with you to resolve the issue.

These limits are subject to change without notice to ensure the stability of our systems. This section will be updated when we change the API limits.

+ Note About Results Accuracy

As mentioned under the "About" section, this service leverages OpenStreetMap (OSM) and Nominatim to perform geocode lookups. The source database is the "full planet" PBF file, taken directly from OSM.

This is a different geocoder system from that used on MAPS, which uses the Google MAPS API for geocoding. Therefore, you can expect that the results from this geocoder will not exactly match those on MAPS.

Please be advised that, although OSM is a very large dataset, it has been noted by some users that the geocoded results from OSM & Nominatim are less accurate than those available via commercial systems, e.g. Google Maps, Mapbox, Esri, etc.

+ Legal / Disclaimers

THIS SERVICE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND.

NO REPRESENTATION IS MADE WITH RESPECT TO THE CONTINUED AVAILABILITY OF THIS SERVICE OR THE ACCURACY OF RESULTS RETURNED BY THIS SERVICE.

YOU ARE FREE TO USE THE RESULTS GENERATED BY THIS GEOCODING SERVICE AS DESIRED ON CONDITION THAT SUCH USAGE COMPLIES WITH THE TERMS OF OPENSTREETMAP ("OSM") AND NOMINATIM.

USE AT YOUR OWN RISK!

+ How Can I Help Or Say Thanks For This Free Service?

Funding for this service is available thanks to our Map Maker (Maps.co).

If you would like to help, we would be grateful if you could share the Map Maker service, e.g. linking to the Map Maker or sharing it on social media.

Page Last Updated: November 30 2023

© Copyright Maps.co