Geocoding API
The Geocoding API enables you to convert any city from any country to latitude and longitude coordinates. For reverse-geocoding, check out our Reverse Geocoding API.
From 2,473 users
Applications using this API
API Status
API Response Times
Average | P50 | P75 | P90 | P95 |
|---|---|---|---|---|
| 194ms | 239ms | 287ms | 671ms | 873ms |
Similar APIs
Didn't find what you were looking for? Suggest an improvement
/v1/geocoding GET
https://api.api-ninjas.com/v1/geocoding
Get current city coordinates by city and country name.
Parameters
At least one of the following parameters must be set:
cityrequiredCity name.
stateoptionalUS state (for United States cities only).
countryoptionalCountry name, 2-letter ISO country code, or 3-letter ISO country code.
zipcodeoptional5-digit zipcode (for United States cities only).
Headers
X-Api-KeyrequiredAPI Key associated with your account.
Response
A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.
nameThe name of the city.
latitudeLatitude coordinate of the city.
longitudeLongitude coordinate of the city.
country2-letter ISO 3166 alpha-2 country code.
Sample Request Live Demo!
https://api.api-ninjas.com/v1/geocoding?city=London&country=GBHeaders
X-Api-KeyLog in or sign up to get your API KeySample Response
Code Examples
1
2
curl -X GET "https://api.api-ninjas.com/v1/geocoding?city=London&country=GB" \
-H "X-Api-Key: YOUR_API_KEY"If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.
Frequently Asked Questions
Can I use the Geocoding API for commercial purposes?
Yes, but you must have a premium subscription. Commercial use of the Geocoding API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.How do I get an API key and start using the Geocoding API?
Sign up for a free account to instantly get your API key, then pass it in theX-Api-Keyheader on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.What happens if I exceed my quota for the month?
Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.What happens if a request to the Geocoding API fails?
The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.How do I disambiguate a city when the same name exists in multiple countries?
Pass thecountryparameter alongsidecity— it accepts a country name, a 2-letter ISO code, or a 3-letter ISO code (for examplecountry=GBfor London). For United States cities you can further narrow results with thestateparameter or a 5-digitzipcode. Browse related location tools in the API catalog.What fields does the Geocoding response include?
It returns a JSON array of objects, each containing the cityname, itslatitudeandlongitudecoordinates, and the 2-letter ISO 3166 alpha-2countrycode. Failed requests return an error instead, as described in our error codes documentation.How do I convert coordinates back into a city name?
The Geocoding endpoint only converts forward, from a city to itslatitudeandlongitude; to go the other direction and resolve coordinates into a location, use our Reverse Geocoding API instead.Can I get more detail about a city beyond its coordinates?
This endpoint returns onlyname,latitude,longitude, andcountry; for richer data such as population or region, use the City API, or look up the local time at those coordinates with the Timezone API.