GET geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&singleLine=1600 Pennsylvania Ave NW, DC&token=<ACCESS_TOKEN> HTTP/1.1Geocoding service
The geocoding service can find addresses, businesses, and places around the world. Address text can be converted to location candidates and a location can be converted into an address. The service provides suggested address candidates for partial address and place-name text. Many addresses can also be geocoded at one time with batch geocoding.
Key features
To get started using the service, you can do the following:
- 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.
- Return the rooftop or street location for PointAddress candidates.
- Specify the type of city name or street name to be included in output fields.
Tip:
Learn more about the geocoding service features and capabilities in the Mapping APIs and location services guide.
Access the services
To access the geocoding service you need the following:
- An ArcGIS Location Platform account or ArcGIS Online account.
- An access token (API key or OAuth 2.0) with the appropriate privilege.
Note:
If you have an ArcGIS Online account:
- The premium:user:geocode:stored privilege is always required for geocodeAddresses and batchGeocode requests, and for findAddressCandidates and reverseGeocode requests when the results are persisted (specifically when parameter forStorage=true is included in the request).
- The premium:user:geocode privilege is required for suggest requests, and for findAddressCandidates and reverseGeocode requests when the results are not persisted.
If you have an ArcGIS Location Platform account:
- The premium:user:geocode:stored privilege is always required for geocodeAddresses and batchGeocode requests, and for findAddressCandidates and reverseGeocode requests when the results are persisted (specifically when parameter forStorage=true is included in the request).
- The premium:user:geocode:temporary privilege is required for suggest requests, and for findAddressCandidates and reverseGeocode requests when the results are not persisted.
Tip:
To learn how to get an API key or to use OAuth 2.0, see Security and authentication in the Mapping APIs and location services guide.
Example
This example shows how to find the location of an address:
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
"location": {
"x": -77.036546998209,
"y": 38.897675107651
},
"score": 100,
"attributes": {
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
"LongLabel": "1600 Pennsylvania Ave NW, Washington, DC, 20500, USA",
"ShortLabel": "1600 Pennsylvania Ave NW",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "1600 Pennsylvania Ave NW, Washington, District of Columbia, 20500",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "1600",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "Pennsylvania",
"StType": "Ave",
"StDir": "NW",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "1600 Pennsylvania Ave NW",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Washington",
"MetroArea": "",
"Subregion": "District of Columbia",
"Region": "District of Columbia",
"RegionAbbr": "DC",
"Territory": "",
"Zone": "",
"Postal": "20500",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -77.036546998209,
"Y": 38.897675107651,
"DisplayX": -77.036546998209,
"DisplayY": 38.897675107651,
"Xmin": -77.037546998209,
"Xmax": -77.035546998209,
"Ymin": 38.896675107651,
"Ymax": 38.898675107651,
"ExInfo": ""
},
"extent": {
"xmin": -77.037546998209,
"ymin": 38.896675107651,
"xmax": -77.035546998209,
"ymax": 38.898675107651
}
}
]
}
To see a live example, go to the Mapping APIs and location services guide.
Tip:
Learn how to access the geocoding service with different ArcGIS and open source APIs in the Mapping APIs and location services guide.