The geocoding service can find addresses, businesses, and places around the world. Address text can be converted to location candidates (forward geocoding) and a location can be converted to an address (reverse geocoding). The service provides suggested address candidates for partial address text and place name search. Many addresses can also be geocoded at one time with batch geocoding.
Places, addresses, and businesses found using the geocoding service.
Key features
- Geocode addresses and find places around the world.
- Filter place search by category type.
- Return candidates in different languages and locales.
- Return candidates in a different spatial reference.
- Refine search by location, extent, city, and country code.
- Return specific data fields for each candidate.
- Limit the number of candidates returned.
- Find a rooftop or street location for
Pointcandidates.Address - Specify the type of city name or street name to be included in output fields.
How the geocoding service works
The geocoding service performs a number of operations:
- Address geocoding: get a location from an address.
- Place geocoding: get a location from a place name.
- Reverse geocoding: get an address or place name from a location.
- Autosuggest: get likely complete search strings for a partial address or place name.
- Batch geocoding: get locations from a set of addresses.
The results from geocoding operations can be used dynamically in-memory (not-stored) or persisted for future use (stored). To learn more about storing results, see Storage parameter.
Service URLs
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/<request>?<parameters>https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/<request>?<parameters>Learn more about standard and enhanced endpoints in Service endpoints.
Required parameters
| Name | Description | Examples |
|---|---|---|
f | The format of the data returned. | f=json f=pjson |
token | An API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication. | token=< token=< |
Storage parameter
If you need to store or persist the geocoding service results in any way, you are required to use the for parameter.
| Name | Description | Example |
|---|---|---|
for | Specifies whether the results of the operation will be persisted. | for |
Address geocoding
To geocode an address, use the find operation.
This returns a JSON structure containing an array of address candidates. Each candidate includes a:
score(between 0-100)- complete
address - point
location - coverage
extent - set of
attributes
URL Request
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address={searchText}&outFields={fieldList}&f=json&token=<ACCESS_TOKEN>https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address={searchText}&outFields={fieldList}&f=json&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Key parameters
out (optional)
A list of attributes to return for each result candidate. If not specified, no attributes are returned.
Use * to return all attributes.
Other parameters
There are many other parameters that can be used to improve and modify geocode results.
Some commonly used parameters are:
max: Limit the number of candidates returned.Locations out: The spatial reference for theS R locationandextent. If not specified, they are returned in WGS84.location: Candidate scores will be weighted to prefer results closer to this location.search: Limit search results to a geographic extent. Candidates outside this extent will not be returned.Extent location: Specify whether theType locationis the candidate'srooftopor astreetlocation suitable for driving directions.for: Specifies whether the results of the operation will be persisted.Storage
Example
Get the top result
Get the best match for 10 Downing Street, London by also specifying to return at most 1 result candidate.
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=10 Downing Street, London&maxLocations=1&f=json&token=<ACCESS_TOKEN>{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "10 Downing Street, London, England, SW1A 2",
"location": {
"x": -0.12766996404513975,
"y": 51.503359983443914
},
"score": 100,
"attributes": {},
"extent": {
"xmin": -0.12866996404513975,
"ymin": 51.50235998344392,
"xmax": -0.12666996404513975,
"ymax": 51.50435998344391
}
}
]
}Place geocoding
To search for a place or POI, use the find operation.
This returns a JSON structure containing an array of place candidates. Each candidate includes a:
score(between 0-100)- complete
address - point
location - coverage
extent - set of
attributes
You can specify a place name to search by name using the singleline parameter, and/or a category to search by type of place. You can also specify a location to search near.
singleline, category, and location are all optional, but you should typically specify at least singleline or category.
URL Request
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine={placeName}&location={longitude,latitude}&category={category}f=json&token=<ACCESS_TOKEN>https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine={placeName}&location={longitude,latitude}&category={category}f=json&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Key parameters
category (optional)
Which type of places to search for. If not specified, all categories are considered.
out (optional)
out specifies which attributes to return for each result candidate. If not specified, no attributes are returned.
Use * to return all attributes.
Other parameters
There are many other parameters that can be used to improve and modify place search results.
Some commonly used parameters are:
max: Limit the number of candidates returned.Locations out: The spatial reference for theS R locationandextent. If not specified, they are returned in WGS84.search: Limit search results to a geographic extent. Candidates outside this extent will not be returned.Extent location: Specify whether theType locationis the candidate'srooftopor astreetlocation suitable for driving directions.for: Specifies whether the results of the operation will be persisted.Storage
Code examples
Get the nearest POI locations by name
Get the nearest Starbucks locations to (lat,lon) 34,-118.2. Note that this translates to (x,y) -118.2,34.
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleline=Starbucks&location=-118.2,34&f=json&token=<ACCESS_TOKEN>{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Starbucks",
"location": {
"x": -118.21380999999997,
"y": 33.988890000000026
},
"score": 100,
"attributes": {},
"extent": {
"xmin": -118.21880999999996,
"ymin": 33.983890000000024,
"xmax": -118.20880999999997,
"ymax": 33.99389000000003
}
},
{
"address": "Starbucks",
"location": {
"x": -118.18505999999996,
"y": 33.98834000000005
},
"score": 100,
"attributes": {},
"extent": {
Get the nearest POI locations by category
Get the nearest Coffee Shop locations to (lat,lon) 34,-118.2. Note that this translates to (x,y) -118.2,34.
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?category=Coffee Shop&location=-118.2,34&f=json&token=<ACCESS_TOKEN>{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Euro Coffee",
"location": {
"x": -118.20613999999995,
"y": 33.99613000000005
},
"score": 100,
"attributes": {},
"extent": {
"xmin": -118.21113999999994,
"ymin": 33.99113000000005,
"xmax": -118.20113999999995,
"ymax": 34.00113000000005
}
},
{
"address": "Universal Coffee",
"location": {
"x": -118.20210999999995,
"y": 34.014500000000055
},
"score": 100,
"attributes": {},
"extent": {
Autosuggest
To get complete text suggestions for partial search text, use the suggest operation.
This returns a JSON structure containing an array of complete search suggestions for incomplete search text, which can be displayed in a UI for the user to choose from. Each suggestion includes text which can be used to make a geocode or place search request.
The suggestion text should be provided to the find operation as the address or singleline parameter to get geocode or place search results.
URL Request
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text={partialText}&f=json&token=<ACCESS_TOKEN>https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text={partialText}&f=json&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Key parameters
Other parameters
Additional parameters can be used to improve the complete suggestions.
Some commonly used parameters are:
location: Complete suggestions will be weighted to prefer those closer to this location.max: Limit the number of complete suggestions to return.Candidates search: Specify an extent to limit search results. Suggestions outside this extent will not be returned.Extent category: See Place search.
To learn more, see the REST API documentation.
Example
Get the search suggestions for partial text
Get the best search completions for the text Amster.
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=Amster&f=json&token=<ACCESS_TOKEN>{
"suggestions": [
{
"text": "Amsterdam, NLD",
"magicKey": "dHA9MCNsb2M9NDI0OTc4MzcjbG5nPTMyI3BsPTQzMDg4MjQyI2xicz0xNDo1MDQxNDE3",
"isCollection": false
},
{
"text": "Amsterdam Airport Gemeente Haarlemmermeer, NLD",
"magicKey": "dHA9MCNsb2M9NDI4MDI5OTgjbG5nPTMyI3BsPTQzNjcyNjA5I2xicz0xNDo1MDQxNDIx",
"isCollection": false
},
{
"text": "Amsterdao Amsterdam, NLD",
"magicKey": "dHA9MCNsb2M9NDI4MDMxMzEjbG5nPTMyI3BsPTQzNjcyNzY1I2xicz0xNDo1MDQxNzI0",
"isCollection": false
},
{
"text": "Amsterdam, NY, USA",
"magicKey": "dHA9MCNsb2M9NDU3NjkyNSNsbmc9MzMjcGw9MTcwMTExMyNsYnM9MTQ6NTA0MTQxNw==",
"isCollection": false
},
{
"text": "Amsterdam, Gert Sibande, Mpumalanga, ZAF",
"magicKey": "dHA9MCNsb2M9NDk5NjMxNDgjbG5nPTMzI3BsPTU0OTg5MTk3I2xicz0xNDo1MDQxNDE3",
"isCollection": false
}
]
}Reverse geocoding
To get the nearest address or place name for a point location, use the reverse operation.
This returns a JSON structure containing a single candidate. The candidate includes:
address: detailed result information.location: The point location of the result.
URL Request
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?location={point}&f=json&token=<ACCESS_TOKEN>https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?location={point}&f=json&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Key parameters
Other parameters
Additional parameters can be used to improve reverse geocode results.
Some commonly used parameters are:
feature: Limit the types of candidates to return (such as Street Address, POI, Street Intersection).Types location: SpecifyType rooftoporstreetto control what the candidatelocationrefers to.lang: Control the language of the returned address.Code for: Specifies whether the results of the operation will be persisted.Storage
Example
Get the nearest intersection
Get the nearest street intersection to (lat,lon) 34,-118.2. Note that this translates to (x,y) -118.2,34.
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?location=-118.2,34&featureTypes=StreetInt&f=json&token=<ACCESS_TOKEN>{
"address": {
"Match_addr": "District Blvd & Everett Ave, Los Angeles, California, 90058",
"LongLabel": "District Blvd & Everett Ave, Los Angeles, CA, 90058, USA",
"ShortLabel": "District Blvd & Everett Ave",
"Addr_type": "StreetInt",
"Type": "",
"PlaceName": "",
"AddNum": "",
"Address": "District Blvd & Everett Ave",
"Block": "",
"Sector": "",
"Neighborhood": "",
"District": "",
"City": "Los Angeles",
"MetroArea": "Los Angeles Metro Area",
"Subregion": "Los Angeles County",
"Region": "California",
"Territory": "",
"Postal": "90058",
"PostalExt": "",
"CountryCode": "USA"
},
"location": {
"x": -118.199789933022,
"y": 33.99992003757502,
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
}
Batch geocoding
To search for multiple places or POIs, use the geocode operation.
This returns a JSON structure containing an array of place candidates. Each candidate includes a:
score(between 0-100)- complete
address - point
location - coverage
extent - set of
attributes
URL Request
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?addresses={records}&f=json&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Authentication
To make authenticated requests you need to use one of the following:
- API key: A permanent token that grants your application access to ready-to-use services and, with an ArcGIS Developer account, private hosted layer (items) and data services.
- User authentication (formerly _ArcGIS identity): Grants a short-lived token, generated via OAuth 2.0, giving your application permission to access the content and services authorized to an existing ArcGIS user's account.
- App credential authentication: Grants a short-lived token, generated via OAuth 2.0, authorizing your application access to ready-to-use services. See usage restrictions.
Learn more about getting access tokens in Security and authentication.
API support
| Geocoding | Reverse Geocoding | Batch Geocoding | Place/POI Search | Autosuggest | UI Component | |
|---|---|---|---|---|---|---|
| ArcGIS Maps SDK for JavaScript | ||||||
| ArcGIS Maps SDK for .NET | 1 | |||||
| ArcGIS Maps SDK for Kotlin | 1 | |||||
| ArcGIS Maps SDK for Swift | 1 | |||||
| ArcGIS Maps SDK for Java | 1 | |||||
| ArcGIS Maps SDK for Qt | 1 | |||||
| ArcGIS API for Python | ||||||
| ArcGIS REST JS | ||||||
| Esri Leaflet | 2 | |||||
| MapLibre GL JS | 2 | 2 | 2 | 2 | 2 | |
| OpenLayers | 2 | 2 | 2 | 2 | 2 |
- 1. No runtime API. Access via HTTP request.
- 2. Access via ArcGIS REST JS.
Pricing
To determine how much it costs to access the service:
- If you have an ArcGIS Developer account, go to Pricing. Transactions are billed in US dollars. A free tier of transactions may be available.
- If you have an ArcGIS Online account, go to Understand credits. Transactions are billed in credits.
Service metadata
The properties and capabilities of the geocoding service are described by metadata JSON that can be accessed here:
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=json&token=<ACCESS_TOKEN>Service data
Source
The main sources for data are HERE and Geonames. Additional sources may be used for different countries. See a complete list of data sources for each country here.
Quality
The service provides geocoding for most countries in the world. The quality of results depends on the data available. The quality is ranked Level 1 (darkest) to Level 4 (lighest); Level 1 being the highest quality.
Language support
Addresses can be returned in a specific language. Different languages are supported for each country. Visit the language table to learn which languages are supported.
Click on the map below to explore the support level.
Tutorials
Search for an address
Convert an address or place to a location with the geocoding service.
Reverse geocode
Get an address, business, or place from coordinates with the geocoding service.
Find place addresses
Find an address, business, or place with the geocoding service.
Display your location
Find and track your device location on a map.