Geocoding service

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 rooftop or street location for PointAddress candidates.
  • 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:

  • Geocoding: get a location from an address.
  • Place search: 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

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/<request>?<parameters>

Learn more about standard and enhanced endpoints in Service endpoints.

Required parameters

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson
tokenAn API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication.token=<YOUR_API_KEY>
token=<ACCESS_TOKEN>

Storage parameter

If you need to store or persist the geocoding service results in any way, you are required to use the forStorage parameter.

NameDescriptionExample
forStorageSpecifies whether the results of the operation will be persisted.forStorage=true

Geocoding

To geocode an address, use the findAddressCandidates 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

Use dark colors for code blocksCopy
 
1
https://geocode-api.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

address or singleline

The address text to search for.

outFields (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:

  • maxLocations: Limit the number of candidates returned.
  • outSR: The spatial reference for the location and extent. If not specified, they are returned in WGS84.
  • location: Candidate scores will be weighted to prefer results closer to this location.
  • searchExtent: Limit search results to a geographic extent. Candidates outside this extent will not be returned.
  • locationType: Specify whether the location is the candidate's rooftop or a street location suitable for driving directions.
  • forStorage: Specifies whether the results of the operation will be persisted.

Example

Get the top result

Get the best match for 10 Downing Street, London by also specifying to return at most 1 result candidate.

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=10 Downing Street, London&maxLocations=1&f=json&token=<ACCESS_TOKEN>

To search for a place or POI, use the findAddressCandidates 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

Use dark colors for code blocksCopy
 
1
https://geocode-api.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

address or singleline (optional)

The place name to search for.

category (optional)

Which type of places to search for. If not specified, all categories are considered.

location (optional)

Candidate scores will be weighted to prefer results closer to this location.

outFields (optional)

outFields 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:

  • maxLocations: Limit the number of candidates returned.
  • outSR: The spatial reference for the location and extent. If not specified, they are returned in WGS84.
  • searchExtent: Limit search results to a geographic extent. Candidates outside this extent will not be returned.
  • locationType: Specify whether the location is the candidate's rooftop or a street location suitable for driving directions.
  • forStorage: Specifies whether the results of the operation will be persisted.

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.

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleline=Starbucks&location=-118.2,34&f=json&token=<ACCESS_TOKEN>

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.

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?category=Coffee Shop&location=-118.2,34&f=json&token=<ACCESS_TOKEN>

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.

URL Request

Use dark colors for code blocksCopy
 
1
https://geocode-api.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

text

The partial search text to get complete search suggestions for.

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.
  • maxCandidates: Limit the number of complete suggestions to return.
  • searchExtent: Specify an extent to limit search results. Suggestions outside this extent will not be returned.
  • 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.

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?text=Amster&f=json&token=<ACCESS_TOKEN>

Reverse geocoding

To get the nearest address or place name for a point location, use the reverseGeocode 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

Use dark colors for code blocksCopy
 
1
https://geocode-api.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

location (optional)

Specify a location to get an address for.

Other parameters

Additional parameters can be used to improve reverse geocode results.

Some commonly used parameters are:

  • featureTypes: Limit the types of candidates to return (such as Street Address, POI, Street Intersection).
  • locationType: Specify rooftop or street to control what the candidate location refers to.
  • langCode: Control the language of the returned address.
  • forStorage: Specifies whether the results of the operation will be persisted.

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.

Use dark colors for code blocksCopy
 
1
https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/reverseGeocode?location=-118.2,34&featureTypes=StreetInt&f=json&token=<ACCESS_TOKEN>

Batch geocoding

To search for multiple places or POIs, use the geocodeAddresses 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

Use dark colors for code blocksCopy
 
1
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/geocodeAddresses?records={addressRecords}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 content (currently in beta).
  • ArcGIS Identity (formerly named user): 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.

Learn more about getting access tokens in Security and authentication.

API support

Full supportPartial supportNo support
  • 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:

  1. If you have an ArcGIS Developer account, go to Pricing.

    Transactions are billed in US dollars. A free tier of transactions may be available.

  2. 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:

Use dark colors for code blocksCopy
 
1
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.

Three text strings geocoded in one transaction with the geocoding service

Tutorials

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.