Geocode an entire list of addresses in one request using the geocode operation. Geocoding many addresses at once is also known as batch or bulk geocoding.
This operation can be used to find the following types of locations:
-
Street addresses
27488 Stanford Ave, Bowden, North Dakota380 New York St, Redlands, CA 92373
-
Administrative place-names, such as city, county, state, province, or country names
Seattle, WashingtonState of MahārāshtraLiechtenstein
-
Postal codes
92591TW9 1 DN
-
Points of interest (POI) by name
Disneyland, Californiastarbucks, 5th Ave, San Diegomount everest
-
Coordinates
-117.155579,32.703761
The addresses in your table can be stored in a single field or in multiple fields—one for each address component. Batch geocoding performance is better when the address parts are stored in separate fields.
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.
Request URL
https
Maximum addresses
There is a limit to the maximum number of addresses that can be geocoded in a single batch request with the service. The Max property defines this limit. For instance, if Max , and a record set sent to the service contains 3,000 addresses, only the first 2,000 will be geocoded. The Suggested property is also useful, as it specifies the optimal number of addresses to include in a single batch request.
Both of these properties can be determined by querying the service description at https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson.
The client application must account for the limit by dividing the input address table into record sets of Max or fewer addresses and send each record set to the service as a separate request. Note that the Generate and Publish operations take care of this for you.
Batch size
For batch geocode operations, the service only returns a response after each address in the input record set has been geocoded. If an unhandled error such as a time-out occurs during the process, the server will not return any results for that request, even if most of the addresses in the input record set have already been geocoded. For this reason, the client application should implement logic to detect and handle such errors.
Response time-outs tend to occur when input addresses are poorly formed or include many extraneous tokens that are not likely to be matched to real address components. The frequency of lost batches due to such time-outs can be mitigated by reducing the number of addresses included in each batch. Follow these general guidelines when choosing a batch size for your operation:
-
If the addresses you want to geocode are poorly formatted, ambiguous, or include many tokens, decrease the batch size to reduce the likelihood of time-outs. For extreme cases, you may need to set the batch size as low as 10 addresses. Be aware that using smaller batches will cause the
geocodeoperation to perform more slowly overall.Addresses -
If the addresses you want to geocode are well-formatted and unambiguous, increase the batch size to improve overall performance. For example, a batch size of 1,000 will result in better performance than smaller batch sizes in this scenario.
Batch geocode access
An ArcGIS Online organizational account is required to use the batch geocoding functionality provided by the ArcGIS Geocoding service. Successfully geocoded addresses that return a status of Matched or Tied cause ArcGIS Online service credits to be consumed for batch geocoding operations.
Each batch geocode request requires a token to be included with the request. Refer to Security and authentication for information about how to generate a token.
Request parameters
The parameters for the geocode operation are listed in the subsections that follow, categorized by required and optional parameters.
Required parameters
addresses
A record set representing the addresses to be geocoded. Each record must include an OBJECTID attribute with a unique value as well as values for the address fields supported by the service.
For passing in the location name as a single line of text—single field batch geocoding—use the Single input field.
For passing in the location name as multiple lines of text—multifield batch geocoding—use the address fields described in findAddressCandidates.
The service info page https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer?f=pjson provides localized versions of the input field names in all locales supported by the service. See Localized input field names for more information.
The service info page also provides the maximum length of strings supported for each address input field. For the Single input field, refer to the length attribute of the single object in the service info page. Currently, the maximum length is 200 characters. For the multifield address input fields, such as address , address2 , address3 , city , postal , and so on, refer to the address object. Within this object, each multifield input field is described by a name attribute as well as a corresponding length attribute. The name attribute value in the service info is the same as the input field name. For example, information about the address field can be found by searching for name = address within the address object.
Example
addresses=
{
"records": [
{
"attributes": {
"OBJECTID": 1,
"Address": "380 New York St",
"Neighborhood": "",
"City": "Redlands",
"Subregion": "",
"Region": "CA"
}
},
{
"attributes": {
"OBJECTID": 2,
"Address": "1 World Way",
"Neighborhood": "",
"City": "Los Angeles",
"Subregion": "",
"Region": "CA"
}
}
]
}token
Use this parameter to specify a token that provides the identity of a user who has the needed permissions to access the service.
See Security and authentication for more information on how to generate an access token.
Example (replace with a valid token)
token=<ACCESS TOKEN>f
The service supports responses in JSON or PJSON format. You can specify the response format using the f parameter. This is a required parameter.
Example
f=jsonOptional parameters
category
A place or address type that can be used to filter geocode results. The parameter supports input of single-category values or multiple comma-separated values. See Category filtering for details about the category parameter.
Example of category filtering with a single category
category=AddressExample of category filtering with multiple categories
category=Address,PostalsourceCountry
A value representing the country. When a value is passed for this parameter, all of the addresses in the input table are sent to the specified country to be geocoded. For example, if source is passed with a batch request, it is assumed that all of the addresses in the table are in the United States, so only matching addresses in the U.S. are returned. Using this parameter can increase batch geocoding performance when all addresses are within a single country.
Acceptable values include the three-character country code. You can specify multiple country codes to limit results to more than one country.
A list of supported countries and codes is available in Data coverage.
Example: Single country
sourceCountry=USAExample: Multiple countries
sourceCountry=FRA,DEU,ESPoutSR
The spatial reference of the x,y coordinates returned by a geocode request. This is useful for applications using a map with a spatial reference different than that of the geocode service.
The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If out is not specified, the spatial reference of the output locations is the same as that of the service. The ArcGIS Geocoding service spatial reference is WGS84 (WKID = 4326).
For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
Example (102100 is the WKID for the Web Mercator projection)
outSR=102100matchOutOfRange
A Boolean that specifies whether StreetAddress matches should be returned even when the input house number is outside of the house number range defined for the input street. Out-of-range matches have = . The geometry of such matches is a point corresponding to the end of the street segment where the range value is closest to the input house number. If match is not specified in a request, its value is set to true by default.
With the match parameter, better spatial accuracy is provided for inexact street address searches. Most street segments are assigned house number ranges. For example, Main Street may include house numbers from 2–100 on one side of the street and 1–99 on the other. A user may search for a house number that is not within this range, such as 109 Main Street. If match is passed in this request, the geocode service will return a StreetName-level match to Main Street, with geometry corresponding to the centroid of a street segment that most closely matches the input values. StreetName matches can be ambiguous because there may be multiple street segments with the same name that equally match the input. However, if match , in this case, a more precise geometry is returned to the specific side of the segment of Main Street with house number range 1–99.
Example
matchOutOfRange=falselocationType
The location parameter specifies whether the output geometry of PointAddress matches should be the rooftop point or street entrance location. Valid values are rooftop and street . The default value is rooftop .
Geocode results include one geometry object (the location object) which defines the location of the address, as well as two sets of x,y coordinate values within the attributes object: X /Y , and DisplayX /DisplayY . In most cases, for geocode results with = or Subaddress , the X /Y attribute values describe the coordinates of the address along the street, while the Display /Display values describe the rooftop, or building centroid, coordinates. By default, the geometry returned for geocode results represents the rooftop location of the address (if the rooftop location is available in the source data). This is useful for most spatial analysis and map display purposes. However, for routing scenarios, it may be desirable to use the street location because the rooftop location of some addresses may be offset from a street by a large distance. For these cases, the location parameter can be used to specify that the street entrance geometry should be returned.
It is important to note that location is limited by the address data sources used by the ArcGIS Geocoding service. Not all PointAddress and Subaddress features include rooftop and street location coordinates. For some addresses, only a rooftop location is available; for others, only a street location is provided by the data source. For cases such as this, the location parameter may not function as expected. For example, if only rooftop location coordinates are available for an address, the rooftop geometry will be returned for the geocoded address even when location is requested.
Example
locationType=streetsearchExtent
A set of bounding box coordinates that limit the search area to a specific region. This is especially useful for applications in which a user will search for places and addresses within the current map extent.
You can specify the spatial reference of the search coordinates, which is necessary if the map spatial reference is different than that of the ArcGIS Geocoding service; otherwise, the spatial reference of the coordinates is assumed to be the same as that of the ArcGIS Geocoding service.
The input can either be a comma-separated list of coordinates defining the bounding box or a JSON envelope object. The spatial reference of the bounding box coordinates can be included if an envelope object is used.
Refer to the Geocode addresses within an extent section below for more details about using search .
Example without a spatial reference
searchExtent=-104,35.6,-94.32,41Example with a spatial reference
searchExtent=
{
"xmin": -13052769,
"ymin": 3951172,
"xmax": -13019630,
"ymax": 3978490,
"spatialReference": {
"wkid": 3395
}
}langCode
The lang parameter sets the language in which geocode results are returned. Addresses and places in many countries are available in more than one language; in these cases, the lang parameter can be used to specify which language should be used for results returned by the geocode operation. This is useful for ensuring that results are returned in the expected language. For example, a web application could be designed to get the browser language and pass it as the lang parameter value in a geocode request.
See the table of supported countries for valid language code values in each country. The Supported Language Codes column provides the valid input values for the lang parameter. Full language names cannot be used with the lang parameter. Only one language code value can be included for the lang parameter in a geocode request.
If the lang parameter isn't included in a request, or if it is included but there are no matching features with the input language code, the resultant match is returned in the language code of the primary matched component from the input search string. Typically, this is either place-name or street name, depending on the search string.
Similarly, when there are multiple supported languages for a country, it doesn't mean that every address in the country is available in each of the languages. It may be the case that addresses are available in multiple languages for only one region of the country, or that each language is exclusive to a different region and there is no overlap. The following are some examples:
- Both English and French are listed as supported languages for Canada. However, there is no overlap between the languages for any addresses in most provinces. In the province of Quebec, only French addresses are available, while English is the only language used for addresses in Ontario.
- In Belgium, where three languages are supported (Dutch, French, and German), addresses are available in the city of Brussels in both Dutch and French. However, in the majority of the country, only a single language is used for addresses.
- In Greece, there is complete address coverage in both Greek and transliterated Greek languages (Greek words represented with Latin characters).
Due to variability of language coverage, the following logic is used to handle the different scenarios that may be encountered.
| Scenario | Result | Example |
|---|---|---|
Only one language is supported for an address, and no | Candidate is returned in the supported language. | Input (address in Geneva, Switzerland):
Output: |
Only one language is supported for an address, and an unsupported language is specified for the | Candidate is returned in the supported language. | Input (address in Geneva, Switzerland):
Output: |
Multiple languages are supported for an address, and no | Candidate is returned in the language of the primary matched component from the input string (street name or place-name). | Input (address in Brussels, Belgium):
Output: |
Multiple languages are supported for an address, and an unsupported language is specified for the | Candidate is returned in the language of the primary matched component from the input string (street name or place-name). | Input (address in Athens, Greece):
Output: |
Multiple languages are supported for an address, and a supported language is specified for the | Candidate is returned in the requested language. | Input (address in Athens, Greece):
Output: |
Example
langCode=frpreferredLabelValues
The preferred parameter allows simple configuration of output fields returned in a response from the ArcGIS Geocoding service by specifying which address component values should be included in output fields. The parameter supports a single value or a comma-delimited collection of values as input. If the parameter is blank or excluded from a request, default address label formats will be used.
A particular address may have multiple city names associated with it. In the United States, for example, all addresses have a ZIP Code (postal code) assigned to them. Each ZIP Code has one or more associated locality names, which are known as postal cities. There is always one primary postal city value for each ZIP Code. ZIP Codes typically have no set boundaries, and the primary postal city name for the ZIP Code that is assigned to an address may be different than the name of the local city that the address is within.
For addresses in the United States, the ArcGIS Geocoding service includes the primary postal city in response output fields by default. As an example, postal code 45420 in Ohio has the primary postal city value Dayton. Addresses in the city of Kettering are assigned this postal code. It means that the default output fields for all geocoded addresses with postal code 45420, even those within the city of Kettering, will include Dayton as the city. To illustrate, if a user searches for 2109 E Dorothy Ln, O , the default match label returned in the response is 2109 E Dorothy Ln, Dayton, Ohio, 45420, even though the address is within the Kettering city limits.
Some organizations may prefer to include the local city name in the response instead of the postal city. The preferred can be used for this purpose. For the previous example, if preferred is included in the request, the output match label in the response will be 2109 E Dorothy Ln, Kettering, Ohio, 45420.
Similarly, streets may be known by multiple names. This is especially true with highways. For example, Pearblossom Hwy in California, which is the primary name, is also known as CA-138. The ArcGIS Geocoding service allows matching to addresses using either name as input, and by default will return the name that was matched to in the response.
Some organizations may prefer that the primary street name be returned in the response even if a user searches for an alternate street name, and they can use the preferred parameter to accomplish this. In other words, if a user searches for C , and preferred is included in the request, the match label returned in the response is Pearblossom Hwy, Pearblossom, California, 93553.
See the following table for supported parameter values.
| Parameter value | Description |
|---|---|
postalCity | Include the primary postal city value in geocoding response output fields, even if it is different than the city name in the geocoding request. This is the primary name assigned to the postal code of the address. |
localCity | Include the primary local city name in geocoding response output fields, even if it is different than the city name in the geocoding request. This is the name of the city that the address is within, and may be different than the postal city. |
matchedCity | If the input city name in a geocoding request matches any of the local city or postal city names associated with an address, include the matched value in geocoding response output fields. If a city name is not included in the input, or is included but doesn't match to anything, default address formats will be used. |
primaryStreet | Include the primary street name in geocoding response output fields, even if it is different than the street name in the geocoding request. |
matchedStreet | If the input street name in a geocoding request matches any of the supported street names assigned to an address, include the matched value in geocoding response output fields. |
Here are additional details about the preferred parameter
- The
preferredparameter takes a comma-delimited collection of values as input.Label Values - The parameter values correspond to two groups—a City group and a Street group, indicated by the suffix of the value name. The
postal,City local, andCity matchedvalues are part of the City group. TheCity primaryandStreet matchedvalues are part of the Street group.Street - A geocode request can include one City value and one Street value—for instance:
preferred.Label Values=primary Street,postal City - A request can only include one value per group. In other words, a request with
preferredis invalid.Label Values=matched City,postal City
Example: Single label value
preferredLabelValues=matchedCityExample: Multiple label values
preferredLabelValues=matchedCity,primaryStreetoutFields
The list of fields to be returned within the attributes object of the geocode response. Descriptions for each of these fields are available in the Service output topic.
Unless otherwise specified, all output fields are returned in a geocode response (refer to this example to see the full set of output fields). The out parameter can be used to limit the result set by allowing specific fields to be returned, which is useful if not all fields are required for a user workflow.
If out is passed in a geocode request, only the minimum set of components is included in the response. This includes the Result field, which is always part of the geocode response no matter which values are defined for the out parameter. The minimum set of objects includes the following:
spatialReference locations(full address and x,y coordinates of the match location)scoreattributes(including theResultoutput field)ID
Examples that return all output fields
outFields=*
outFields=Example that returns a partial set of output fields
outFields=AddNum,StAddr,CityExample that returns the minimum set of output fields
outFields=noneBatch geocoding output fields
When geocoding a table of addresses, the output fields are returned as part of the attributes in the response. See the example JSON response below, which shows all of the output fields that are returned for each record from a batch geocode process. The output fields are described in the Service output topic.
With batch geocoding, it is useful to define a unique ID for each record in your input table of addresses. You can pass the ID as the OBJECTID in the batch geocode request, and the ID will be returned as the Result in the response. The Result can then be used to link the output fields in the response records, including the x,y location, to the attributes in the original table.
Batch geocoding examples
The following examples illustrate how to format JSON batch geocoding requests for multiline address input (first example) and single-line input (second example) scenarios. In both cases, the response contains the same information.
Example: Batch geocode two addresses
Input multiline JSON record set (URL encoded):
https
For clarity, here is the addresses parameter in PJSON:
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"Address": "380 New York St.",
"City": "Redlands",
"Region": "CA",
"Postal": "92373"
}
},
{
"attributes": {
"OBJECTID": 2,
"Address": "1 World Way",
"City": "Los Angeles",
"Region": "CA",
"Postal": "90045"
}
}
]
}Here is the input single-field JSON record set (URL encoded):
https
For clarity, here is the addresses parameter in PJSON:
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"SingleLine": "380 New York St., Redlands, CA, 92373"
}
},
{
"attributes": {
"OBJECTID": 2,
"SingleLine": "1 World Way, Los Angeles, CA, 90045"
}
}
]
}JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "1 World Way, Los Angeles, California, 90045",
"location": {
"x": -118.398178349434,
"y": 33.944692934838
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "1 World Way, Los Angeles, California, 90045",
"LongLabel": "1 World Way, Los Angeles, CA, 90045, USA",
"ShortLabel": "1 World Way",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "1 World Way, Los Angeles, California, 90045",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "1",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "World",
"StType": "Way",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "1 World Way",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Los Angeles",
"MetroArea": "",
"Subregion": "Los Angeles County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "90045",
"PostalExt": "5803",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -118.398119676112,
"Y": 33.945061151844,
"DisplayX": -118.398178349434,
"DisplayY": 33.944692934838,
"Xmin": -118.399178349434,
"Xmax": -118.397178349434,
"Ymin": 33.943692934838,
"Ymax": 33.945692934838,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": "Transport"
}
},
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -117.195426038092,
"y": 34.056097983409
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "380 New York St, Redlands, California, 92373",
"LongLabel": "380 New York St, Redlands, CA, 92373, USA",
"ShortLabel": "380 New York St",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "380 New York St, Redlands, California, 92373",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "380",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "New York",
"StType": "St",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "380 New York St",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Redlands",
"MetroArea": "",
"Subregion": "San Bernardino County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92373",
"PostalExt": "8118",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.195658887362,
"Y": 34.056466284234,
"DisplayX": -117.195426038092,
"DisplayY": 34.056097983409,
"Xmin": -117.196426038092,
"Xmax": -117.194426038092,
"Ymin": 34.055097983409,
"Ymax": 34.057097983409,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": "Office"
}
}
]
}Category filtering
The geocode operation supports batch geocode filtering by category values, which represent address and place types. By including the category parameter in a geocode request, you can avoid false positive matches to unexpected place and address types due to ambiguous input.
For example, a user has a table of three-letter airport codes that they want to geocode. There may be city or business names that are the same as an airport code, causing false positive matches to other places. However the user can ensure that only airport matches are returned by specifying category=airport in the request.
Example: Batch geocode airport codes with category
Here is the input single field JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "LAX",
"location": {
"x": -118.4085523,
"y": 33.9435233
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "LAX",
"LongLabel": "LAX, 1 World Way, Los Angeles, CA, 90045, USA",
"ShortLabel": "LAX",
"Addr_type": "POI",
"Type": "Airport",
"PlaceName": "LAX",
"Place_addr": "1 World Way, Los Angeles, California, 90045",
"Phone": "(855) 463-5252",
"URL": "www.lawa.org/welcomeLAX.aspx",
"Rank": 9,
"AddBldg": "",
"AddNum": "1",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "World",
"StType": "Way",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "1 World Way",
"Block": "",
"Sector": "",
"Nbrhd": "Westchester",
"District": "",
"City": "Los Angeles",
"MetroArea": "",
"Subregion": "Los Angeles County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "90045",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -118.405581418239,
"Y": 33.945016955146,
"DisplayX": -118.4085523,
"DisplayY": 33.9435233,
"Xmin": -118.4295523,
"Xmax": -118.3875523,
"Ymin": 33.9225233,
"Ymax": 33.9645233,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "SFO",
"location": {
"x": -122.3895912,
"y": 37.6154824
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "SFO",
"LongLabel": "SFO, Us Hwy 101, San Francisco, CA, 94128, USA",
"ShortLabel": "SFO",
"Addr_type": "POI",
"Type": "Airport",
"PlaceName": "SFO",
"Place_addr": "Us Hwy 101, San Francisco, California, 94128",
"Phone": "(800) 435-9736",
"URL": "flysfo.com",
"Rank": 9,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "Us Hwy 101",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "Us Hwy 101",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "San Francisco",
"MetroArea": "",
"Subregion": "San Mateo County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "94128",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -122.386902201643,
"Y": 37.614962219089,
"DisplayX": -122.3895912,
"DisplayY": 37.6154824,
"Xmin": -122.4105912,
"Xmax": -122.3685912,
"Ymin": 37.5944824,
"Ymax": 37.6364824,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}You can also use category filtering to avoid low resolution fallback matches. By default, if the ArcGIS Geocoding service cannot find a match for an input address, it will automatically search for a lower match level, such as a street name, city, or postal code. For batch geocoding, a user may prefer that no match is returned in such cases so that they are not charged for the geocode. If a user passes category= in a geocode request, no fallback will occur if address matches cannot be found; the user will only be charged for the address matches.
Example: Batch geocode with fallback allowed (no category)
Here is the input single field JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "Escondido, California",
"location": {
"x": -117.0853571,
"y": 33.130363
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "Escondido, California",
"LongLabel": "Escondido, CA, USA",
"ShortLabel": "Escondido",
"Addr_type": "Locality",
"Type": "City",
"PlaceName": "Escondido",
"Place_addr": "Escondido, California",
"Phone": "",
"URL": "",
"Rank": 8.5,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Escondido",
"MetroArea": "",
"Subregion": "San Diego County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.0853571,
"Y": 33.130363,
"DisplayX": -117.0853571,
"DisplayY": 33.130363,
"Xmin": -117.1623571,
"Xmax": -117.0083571,
"Ymin": 33.053363,
"Ymax": 33.207363,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -117.195426038092,
"y": 34.056097983409
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "380 New York St, Redlands, California, 92373",
"LongLabel": "380 New York St, Redlands, CA, 92373, USA",
"ShortLabel": "380 New York St",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "380 New York St, Redlands, California, 92373",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "380",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "New York",
"StType": "St",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "380 New York St",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Redlands",
"MetroArea": "",
"Subregion": "San Bernardino County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92373",
"PostalExt": "8118",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.195658887362,
"Y": 34.056466284234,
"DisplayX": -117.195426038092,
"DisplayY": 34.056097983409,
"Xmin": -117.196426038092,
"Xmax": -117.194426038092,
"Ymin": 34.055097983409,
"Ymax": 34.057097983409,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": "Office"
}
}
]
}Example: Batch geocode with no fallback allowed (category= )
Here is the input single field JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "",
"score": 0,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "U",
"Score": 0,
"Match_addr": "",
"LongLabel": "",
"ShortLabel": "",
"Addr_type": "",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": 0.0,
"Y": 0.0,
"DisplayX": 0.0,
"DisplayY": 0.0,
"Xmin": 0.0,
"Xmax": 0.0,
"Ymin": 0.0,
"Ymax": 0.0,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -117.195426038092,
"y": 34.056097983409
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "380 New York St, Redlands, California, 92373",
"LongLabel": "380 New York St, Redlands, CA, 92373, USA",
"ShortLabel": "380 New York St",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "380 New York St, Redlands, California, 92373",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "380",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "New York",
"StType": "St",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "380 New York St",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Redlands",
"MetroArea": "",
"Subregion": "San Bernardino County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92373",
"PostalExt": "8118",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.195658887362,
"Y": 34.056466284234,
"DisplayX": -117.195426038092,
"DisplayY": 34.056097983409,
"Xmin": -117.196426038092,
"Xmax": -117.194426038092,
"Ymin": 34.055097983409,
"Ymax": 34.057097983409,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": "Office"
}
}
]
}See the topic Category filtering for details.
Batch geocoding coordinates
The ArcGIS Geocoding service supports batch geocoding of coordinates with the geocode operation. The output is a geometry point with a match address that is the same as the input coordinates. This is different than reverse geocoding, in which input x,y coordinates are resolved to a matching street address; see reverseGeocode for more information. The following types of coordinates are supported for batch geocoding:
- x,y coordinates; x refers to longitude (east-west coordinates), and y refers to latitude (north-south coordinates)
- Military Grid Reference System (MGRS) coordinates
- United States National Grid (USNG) coordinates
Detailed information about valid input formats for coordinate geocoding is provided in the findAddressCandidates topic. Examples for batch geocoding coordinates with the geocode operation are provided below.
Example: Batch geocode latitude/longitude coordinates
Here is the input single field JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "Y:47.528360 X:18.991954",
"location": {
"x": 18.9919543,
"y": 47.5283605
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "Y:47.528360 X:18.991954",
"LongLabel": "47°31'42.097\"N 18°59'31.035\"E",
"ShortLabel": "Y:47.528360 X:18.991954",
"Addr_type": "YX",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": 18.9919543,
"Y": 47.5283605,
"DisplayX": 18.9919543,
"DisplayY": 47.5283605,
"Xmin": 18.9909543,
"Xmax": 18.9929543,
"Ymin": 47.5273605,
"Ymax": 47.5293605,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "18.991954 47.528360",
"location": {
"x": 18.9919543,
"y": 47.5283605
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "18.991954 47.528360",
"LongLabel": "47°31'42.097\"N 18°59'31.035\"E",
"ShortLabel": "18.991954 47.528360",
"Addr_type": "LatLong",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": 18.9919543,
"Y": 47.5283605,
"DisplayX": 18.9919543,
"DisplayY": 47.5283605,
"Xmin": 18.9909543,
"Xmax": 18.9929543,
"Ymin": 47.5273605,
"Ymax": 47.5293605,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Example: Batch geocode MGRS coordinates
Here is the input single field JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "19TDJ5538855106",
"location": {
"x": -69.555020740502,
"y": 43.847689826831
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "19TDJ5538855106",
"LongLabel": "19TDJ5538855106",
"ShortLabel": "19TDJ5538855106",
"Addr_type": "MGRS",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": -69.555020740502,
"Y": 43.847689826831,
"DisplayX": -69.555020740502,
"DisplayY": 43.847689826831,
"Xmin": -69.556020740502,
"Xmax": -69.554020740502,
"Ymin": 43.846689826831,
"Ymax": 43.848689826831,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "18SUH6789043210",
"location": {
"x": -76.511416672563,
"y": 38.327287449633
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "18SUH6789043210",
"LongLabel": "18SUH6789043210",
"ShortLabel": "18SUH6789043210",
"Addr_type": "MGRS",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": -76.511416672563,
"Y": 38.327287449633,
"DisplayX": -76.511416672563,
"DisplayY": 38.327287449633,
"Xmin": -76.512416672563,
"Xmax": -76.510416672563,
"Ymin": 38.326287449633,
"Ymax": 38.328287449633,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Batch geocoding points of interest (POI)
The ArcGIS Geocoding service supports batch geocoding of POIs with the geocode operation. A POI is a named point location that can represent a cultural or geographic landmark or a business. For example, you can find amusement parks, museums, schools, restaurants, hotels, gas stations, or other types of businesses or landmarks, as well as geographic features, such as mountains, lakes, rivers, or deserts.
As with street addresses, you can search for POIs with geocode using the single-field or multifield approach.
Single-field POI search
To search for POIs with single-field search, use the single parameter. In general, valid single POI search strings can be formatted in variations of three basic structures:
- <name> <optional connector> <zone>
- <zone> <name>
- <name><address><zone>
Where
- <name> = A place-name, such as Disneyland, Starbucks, or Niagra Falls.
- <zone> = A postal code or administrative boundary—such as neighborhood, city, subregion, region, country, or any combination thereof—that provides a spatial boundary to the search. It can be included in the search to limit matching candidates but is not required.
- <optional connector> =
inorat; this is not required for the search. - <address> = A street name, such as
Main St, or a complete street address, such as590 N Main St.
Examples of valid single search strings include the following:
Business name searches
- Starbucks San Diego
- Starbucks in San Diego
- San Diego Starbucks
- Starbucks 92101
- Starbucks 5th Ave San Diego
- Reuben H Fleet Science Center, 1875 El Prado, San Diego, CA, 92101, USA
Multifield POI search
When searching for POIs using multifield input, the name of the POI must be passed as the value for the address parameter. The zone information can be passed in the postal , neighborhood , city , subregion , region , and country parameters. If searching for POI + address, the address should be passed as the value for the address2 parameter.
Examples
Example: Batch geocode amusement parks
Here is the input single-field JSON record set:
https
Here is the input multifield JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "Disneyland",
"location": {
"x": -117.9189585,
"y": 33.8099461
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "Disneyland",
"LongLabel": "Disneyland, 1313 S Harbor Blvd, Anaheim, CA, 92802, USA",
"ShortLabel": "Disneyland",
"Addr_type": "POI",
"Type": "Amusement Park",
"PlaceName": "Disneyland",
"Place_addr": "1313 S Harbor Blvd, Anaheim, California, 92802",
"Phone": "(714) 781-4636",
"URL": "disneyland.disney.go.com",
"Rank": 4.5,
"AddBldg": "",
"AddNum": "1313",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "L",
"StPreDir": "S",
"StPreType": "",
"StName": "Harbor",
"StType": "Blvd",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "1313 S Harbor Blvd",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Anaheim",
"MetroArea": "",
"Subregion": "Orange County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92802",
"PostalExt": "2309",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.915410775663,
"Y": 33.803779450016,
"DisplayX": -117.9189585,
"DisplayY": 33.8099461,
"Xmin": -117.9249585,
"Xmax": -117.9129585,
"Ymin": 33.8039461,
"Ymax": 33.8159461,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "Universal Studios",
"location": {
"x": -118.3541,
"y": 34.1360467
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "Universal Studios",
"LongLabel": "Universal Studios, Universal City, CA, 91608, USA",
"ShortLabel": "Universal Studios",
"Addr_type": "POI",
"Type": "Tourist Attraction",
"PlaceName": "Universal Studios",
"Place_addr": "Universal City, California, 91608",
"Phone": "",
"URL": "www.universalstudioshollywood.com/web/en/us",
"Rank": 4.5,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "Universal City",
"District": "",
"City": "Universal City",
"MetroArea": "",
"Subregion": "Los Angeles County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "91608",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -118.354365287235,
"Y": 34.135884342536,
"DisplayX": -118.3541,
"DisplayY": 34.1360467,
"Xmin": -118.3591,
"Xmax": -118.3491,
"Ymin": 34.1310467,
"Ymax": 34.1410467,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Example: Batch geocode place-names with addresses
Here is the input single-field JSON record set:
https
Here is the input multifield JSON record set:
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "San Diego Zoo",
"location": {
"x": -117.1491061,
"y": 32.7352775
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "San Diego Zoo",
"LongLabel": "San Diego Zoo, 2920 Zoo Dr, San Diego, CA, 92101, USA",
"ShortLabel": "San Diego Zoo",
"Addr_type": "POI",
"Type": "Zoo",
"PlaceName": "San Diego Zoo",
"Place_addr": "2920 Zoo Dr, San Diego, California, 92101",
"Phone": "(619) 231-1515",
"URL": "www.sandiegozoo.org",
"Rank": 15,
"AddBldg": "",
"AddNum": "2920",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "R",
"StPreDir": "",
"StPreType": "",
"StName": "Zoo",
"StType": "Dr",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "2920 Zoo Dr",
"Block": "",
"Sector": "",
"Nbrhd": "Balboa Park",
"District": "",
"City": "San Diego",
"MetroArea": "",
"Subregion": "San Diego County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92101",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.147297117657,
"Y": 32.735370287668,
"DisplayX": -117.1491061,
"DisplayY": 32.7352775,
"Xmin": -117.1541061,
"Xmax": -117.1441061,
"Ymin": 32.7302775,
"Ymax": 32.7402775,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "Starbucks",
"location": {
"x": -117.159905,
"y": 32.707766
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "Starbucks",
"LongLabel": "Starbucks, 209 5th Ave, San Diego, CA, 92101, USA",
"ShortLabel": "Starbucks",
"Addr_type": "POI",
"Type": "Coffee Shop",
"PlaceName": "Starbucks",
"Place_addr": "209 5th Ave, San Diego, California, 92101",
"Phone": "(619) 234-0749",
"URL": "",
"Rank": 19,
"AddBldg": "",
"AddNum": "209",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "5th",
"StType": "Ave",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "209 5th Ave",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "San Diego",
"MetroArea": "",
"Subregion": "San Diego County",
"Region": "California",
"RegionAbbr": "CA",
"Territory": "",
"Zone": "",
"Postal": "92101",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -117.159905,
"Y": 32.707766,
"DisplayX": -117.159905,
"DisplayY": 32.707766,
"Xmin": -117.160905,
"Xmax": -117.158905,
"Ymin": 32.706766,
"Ymax": 32.708766,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Geocode addresses within an extent
The geocode operation allows spatial filtering of search results by using the search parameter. If you want to confine a search to a localized area, something that is especially useful in a mobile application, you can define a bounding rectangle to search within. No candidates outside of the rectangle are returned. When bounding rectangle coordinates are entered as a simple comma-separated string in the format <lower left corner>,<upper right corner>, the coordinates must be in the default spatial reference of the geocode service, which is WGS84. The search parameter can be used with all supported search types (street address, POI, admin place, postal code).
The example URL below illustrates how to exclude candidates that are outside a specified extent from being returned by using the search parameter. In this example, two addresses are passed to geocode , along with a search value corresponding to downtown Detroit. Only one of the input addresses is located within the extent, and no match is returned for the other address.
Example: Only return address matches in downtown Detroit using searchExtent with default spatial reference
Single-field request URL
https
Multifield request URL
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "315 Bagley, Detroit, Michigan, 48226",
"location": {
"x": -83.053157815269,
"y": 42.333638711057
},
"score": 98.04,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "M",
"Score": 98.04,
"Match_addr": "315 Bagley, Detroit, Michigan, 48226",
"LongLabel": "315 Bagley, Detroit, MI, 48226, USA",
"ShortLabel": "315 Bagley",
"Addr_type": "PointAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "315 Bagley, Detroit, Michigan, 48226",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "315",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "Bagley",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "315 Bagley",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Detroit",
"MetroArea": "",
"Subregion": "Wayne County",
"Region": "Michigan",
"RegionAbbr": "MI",
"Territory": "",
"Zone": "",
"Postal": "48226",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -83.053414972058,
"Y": 42.333855802349,
"DisplayX": -83.053157815269,
"DisplayY": 42.333638711056,
"Xmin": -83.054157815269,
"Xmax": -83.052157815269,
"Ymin": 42.332638711056,
"Ymax": 42.334638711056,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": ""
}
},
{
"address": "",
"score": 0,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "U",
"Score": 0,
"Match_addr": "",
"LongLabel": "",
"ShortLabel": "",
"Addr_type": "",
"Type": "",
"PlaceName": "",
"Place_addr": "",
"Phone": "",
"URL": "",
"Rank": 0,
"AddBldg": "",
"AddNum": "",
"AddNumFrom": "",
"AddNumTo": "",
"AddRange": "",
"Side": "",
"StPreDir": "",
"StPreType": "",
"StName": "",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "",
"MetroArea": "",
"Subregion": "",
"Region": "",
"RegionAbbr": "",
"Territory": "",
"Zone": "",
"Postal": "",
"PostalExt": "",
"Country": "",
"CntryName": "",
"LangCode": "",
"Distance": 0,
"X": 0.0,
"Y": 0.0,
"DisplayX": 0.0,
"DisplayY": 0.0,
"Xmin": 0.0,
"Xmax": 0.0,
"Ymin": 0.0,
"Ymax": 0.0,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Specify different city and street names for output fields
The preferred parameter allows limited customization of output values in geocode responses. Refer to the parameter overview for details about its functionality; this section includes examples showing how it can be used.
The parameter can be used to override the default city and street names returned in output fields for a geocoding transaction. The default values are based on country addressing conventions and data availability. For instance, United States addresses returned by the ArcGIS Geocoding service include the primary city name assigned to the postal code that is associated with the address; this is known as the postal city name. Sometimes the postal city name is different than the name of the city whose boundaries the address is within (known as the local city name). Streets may be known by multiple names as well. For streets that have more than one name, the ArcGIS Geocoding service returns the name that was matched to from the request in the geocoding results by default.
For the following addresses, the streets have multiple names and the local city name differs from the postal city name.
| Address | Primary street name | Alternate street name | Local city name | Postal city name |
|---|---|---|---|---|
635 CR-30, Olmstedville, NY 12857 | Church Rd | CR-30 | Town of Minerva | Olmstedville |
7608 National Pike, Uniontown, Pennsylvania, 15401 | US-40 | National Pike | Menallen Township | Uniontown |
The examples below illustrate how to modify the city and street names returned in a batch geocode response for these addresses by using the preferred parameter. The first example shows what the geocode results look like without preferred . The second example shows how to use preferred to return the primary street names and local city names in geocoding results for the same input addresses.
Here is what the addresses parameter looks like in PJSON for the example addresses in single-field format (use with POST requests):
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"SingleLine": "635 CR-30, Olmstedville, NY 12857"
}
},
{
"attributes": {
"OBJECTID": 2,
"SingleLine": "7608 National Pike, Uniontown, Pennsylvania, 15401"
}
}
]
}Here is what the addresses parameter looks like in PJSON for these addresses in multifield format (use with POST requests):
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"Address": "635 CR-30",
"City": "Olmstedville",
"Region": "NY",
"Postal": "12857"
}
},
{
"attributes": {
"OBJECTID": 2,
"Address": "7608 National Pike",
"City": "Uniontown",
"Region": "Pennsylvania",
"Postal": "15401"
}
}
]
}Without using the preferred parameter in the geocode request for these addresses, the alternate street names and postal city names are shown in the output geocoding results.
Batch geocode two addresses without preferredLabelValues
Single-field request URL (GET example)
https
Multifield request URL (GET example)
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "635 County Highway 30, Olmstedville, New York, 12857",
"location": {
"x": -73.931301357812,
"y": 43.77195695338
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "635 County Highway 30, Olmstedville, New York, 12857",
"LongLabel": "635 County Highway 30, Olmstedville, NY, 12857, USA",
"ShortLabel": "635 County Highway 30",
"Addr_type": "StreetAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "635 County Highway 30, Olmstedville, New York, 12857",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "635",
"AddNumFrom": "699",
"AddNumTo": "607",
"AddRange": "607-699",
"Side": "R",
"StPreDir": "",
"StPreType": "",
"StName": "County Highway 30",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "635 County Highway 30",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Olmstedville",
"MetroArea": "",
"Subregion": "Essex County",
"Region": "New York",
"RegionAbbr": "NY",
"Territory": "",
"Zone": "",
"Postal": "12857",
"PostalExt": "1828",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -73.931301357812,
"Y": 43.77195695338,
"DisplayX": -73.931301357812,
"DisplayY": 43.77195695338,
"Xmin": -73.932301357812,
"Xmax": -73.930301357812,
"Ymin": 43.77095695338,
"Ymax": 43.77295695338,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "7608 National Pike, Uniontown, Pennsylvania, 15401",
"location": {
"x": -79.777306142717,
"y": 39.933194907282
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "7608 National Pike, Uniontown, Pennsylvania, 15401",
"LongLabel": "7608 National Pike, Uniontown, PA, 15401, USA",
"ShortLabel": "7608 National Pike",
"Addr_type": "StreetAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "7608 National Pike, Uniontown, Pennsylvania, 15401",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "7608",
"AddNumFrom": "7614",
"AddNumTo": "7572",
"AddRange": "7572-7614",
"Side": "L",
"StPreDir": "",
"StPreType": "",
"StName": "National",
"StType": "Pike",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "7608 National Pike",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Uniontown",
"MetroArea": "",
"Subregion": "Fayette County",
"Region": "Pennsylvania",
"RegionAbbr": "PA",
"Territory": "",
"Zone": "",
"Postal": "15401",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -79.777306142717,
"Y": 39.933194907282,
"DisplayX": -79.777306142717,
"DisplayY": 39.933194907282,
"Xmin": -79.778306142717,
"Xmax": -79.776306142717,
"Ymin": 39.932194907282,
"Ymax": 39.934194907282,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}By including preferred in the geocode request for the same input addresses, the output street and city names are different than the previous example.
Batch geocode two addresses with preferredLabelValues=localCity,primaryStreet
Single-field request URL (GET example)
https
Multifield request URL (GET example)
https
For clarity, here is the addresses parameter in PJSON:
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"Address": "635 CR-30",
"City": "Olmstedville",
"Region": "NY",
"Postal": "12857"
}
},
{
"attributes": {
"OBJECTID": 2,
"Address": "7608 National Pike",
"City": "Uniontown",
"Region": "Pennsylvania",
"Postal": "15401"
}
}
]
}JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "635 Morse Memorial Hwy, Minerva, New York, 12857",
"location": {
"x": -73.931301357812,
"y": 43.77195695338
},
"score": 100,
"attributes": {
"ResultID": 1,
"Loc_name": "World",
"Status": "T",
"Score": 100,
"Match_addr": "635 Morse Memorial Hwy, Minerva, New York, 12857",
"LongLabel": "635 Morse Memorial Hwy, Minerva, NY, 12857, USA",
"ShortLabel": "635 Morse Memorial Hwy",
"Addr_type": "StreetAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "635 Morse Memorial Hwy, Minerva, New York, 12857",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "635",
"AddNumFrom": "699",
"AddNumTo": "607",
"AddRange": "607-699",
"Side": "R",
"StPreDir": "",
"StPreType": "",
"StName": "Morse Memorial",
"StType": "",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "635 Morse Memorial Hwy",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Minerva",
"MetroArea": "",
"Subregion": "Essex County",
"Region": "New York",
"RegionAbbr": "NY",
"Territory": "",
"Zone": "",
"Postal": "12857",
"PostalExt": "1828",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -73.931301357812,
"Y": 43.77195695338,
"DisplayX": -73.931301357812,
"DisplayY": 43.77195695338,
"Xmin": -73.932301357812,
"Xmax": -73.930301357812,
"Ymin": 43.77095695338,
"Ymax": 43.77295695338,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
},
{
"address": "7608 National Pike, Menallen, Pennsylvania, 15401",
"location": {
"x": -79.777306142717,
"y": 39.933194907282
},
"score": 100,
"attributes": {
"ResultID": 2,
"Loc_name": "World",
"Status": "M",
"Score": 100,
"Match_addr": "7608 National Pike, Menallen, Pennsylvania, 15401",
"LongLabel": "7608 National Pike, Menallen, PA, 15401, USA",
"ShortLabel": "7608 National Pike",
"Addr_type": "StreetAddress",
"Type": "",
"PlaceName": "",
"Place_addr": "7608 National Pike, Menallen, Pennsylvania, 15401",
"Phone": "",
"URL": "",
"Rank": 20,
"AddBldg": "",
"AddNum": "7608",
"AddNumFrom": "7614",
"AddNumTo": "7572",
"AddRange": "7572-7614",
"Side": "L",
"StPreDir": "",
"StPreType": "",
"StName": "National",
"StType": "Pike",
"StDir": "",
"BldgType": "",
"BldgName": "",
"LevelType": "",
"LevelName": "",
"UnitType": "",
"UnitName": "",
"SubAddr": "",
"StAddr": "7608 National Pike",
"Block": "",
"Sector": "",
"Nbrhd": "",
"District": "",
"City": "Menallen",
"MetroArea": "",
"Subregion": "Fayette County",
"Region": "Pennsylvania",
"RegionAbbr": "PA",
"Territory": "",
"Zone": "",
"Postal": "15401",
"PostalExt": "",
"Country": "USA",
"CntryName": "United States",
"LangCode": "ENG",
"Distance": 0,
"X": -79.777306142717,
"Y": 39.933194907282,
"DisplayX": -79.777306142717,
"DisplayY": 39.933194907282,
"Xmin": -79.778306142717,
"Xmax": -79.776306142717,
"Ymin": 39.932194907282,
"Ymax": 39.934194907282,
"ExInfo": "",
"StrucType": "",
"StrucDet": ""
}
}
]
}Specify output fields
The geocode operation allows you to specify individual output fields or return all output fields in a response. The out parameter is used for this. If you want to return all supported output fields, set out , out , or exclude the parameter from the request. If you only want to return the minimum set of default output fields, set out . If you want to return specific fields, pass the desired field names as comma-separated values in the request, such as out .
See Service output for details about the fields returned by a geocode request.
The examples below illustrate how to control the fields that are included in a geocode response by using the out parameter. The first example shows what the geocode results look like when a partial set of output fields is defined for out . The second example shows how to use out to return the minimum set of default output fields.
Here is what the addresses parameter looks like in PJSON for the example addresses in single-field format (use with POST requests):
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"SingleLine": "269 Lonsdale St, Melbourne, Victoria"
}
},
{
"attributes": {
"OBJECTID": 2,
"SingleLine": "30 Flemington Rd, Melbourne, Victoria"
}
}
]
}Here is what the addresses parameter looks like in PJSON for these addresses in multifield format (use with POST requests):
addresses=
{ "records": [
{
"attributes": {
"OBJECTID": 1,
"Address": "269 Lonsdale St",
"City": "Melbourne",
"Region": "Victoria"
}
},
{
"attributes": {
"OBJECTID": 2,
"Address": "30 Flemington Rd",
"City": "Melbourne",
"Region": "Victoria"
}
}
]
}By default, all output fields are returned in a geocode response. For some workflows or applications, this may cause the response to be larger than necessary. The out parameter can be used to limit the result set so that only the fields required by the application are returned. The example below shows how to return basic address and administrative zone fields in the response.
Batch geocode two addresses and use outFields to return a partial set of output fields (outFields=Addr_type,AddNum,StName,StType,Nbrhd,City,Region,Postal,Country)
Single-field request URL (GET example)
https
Multifield request URL (GET example)
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "269 Lonsdale St, Melbourne, Victoria, 3000",
"location": {
"x": 144.963701807411,
"y": -37.812085793266
},
"score": 100,
"attributes": {
"ResultID": 1,
"Addr_type": "PointAddress",
"AddNum": "269",
"StName": "Lonsdale",
"StType": "St",
"Nbrhd": "Melbourne",
"City": "Melbourne",
"Region": "Victoria",
"Postal": "3000",
"Country": "AUS"
}
},
{
"address": "30 Flemington Rd, Parkville, Melbourne, Victoria, 3052",
"location": {
"x": 144.954186922384,
"y": -37.797494785766
},
"score": 100,
"attributes": {
"ResultID": 2,
"Addr_type": "PointAddress",
"AddNum": "30",
"StName": "Flemington",
"StType": "Rd",
"Nbrhd": "Parkville",
"City": "Melbourne",
"Region": "Victoria",
"Postal": "3052",
"Country": "AUS"
}
}
]
}To reduce the response size even more, set out in the request.
Batch geocode two addresses and use outFields to return the minimum set of output fields (outFields=none)
Single-field request URL (GET example)
https
Multifield request URL (GET example)
https
JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"locations": [
{
"address": "269 Lonsdale St, Melbourne, Victoria, 3000",
"location": {
"x": 144.963701807411,
"y": -37.812085793266
},
"score": 100,
"attributes": {
"ResultID": 1
}
},
{
"address": "30 Flemington Rd, Parkville, Melbourne, Victoria, 3052",
"location": {
"x": 144.954186922384,
"y": -37.797494785766
},
"score": 100,
"attributes": {
"ResultID": 2
}
}
]
}Handling JSON responses
The geocode REST operation results in an output JSON response. However, the REST request may not always successfully return results. A variety of things could cause a REST request to fail:
- Incorrect authentication (token required or invalid token).
- Incorrect syntax in the request. Ensure the request being sent is properly formatted.
- Internet connectivity issues.
- Server time-out.
You can write code to handle these request failures caused by server time-outs. When a time-out occurs, your code will need to do the following:
- Recognize the time-out in the JSON response.
- Split the request into smaller batch sizes and resubmit the request as two separate requests. Each new request will be half the size of the original request and will contain half the addresses.
- See whether each request succeeds. If one of the batches fails due to a time-out, continue the process of splitting the failing batch in two and sending both requests.
- If a request is sent with only one address and it times out, manually write that record as unmatched and continue processing requests.
- Continue this process until all batch requests have completed successfully.
The retry logic described above is the recommended best practice when using the geocode operation. The Geocode Addresses, Geocode File, and Geocode Locations from Table geoprocessing tools in ArcGIS Pro already use this logic to ensure batch geocoding never fails against a geocode service.