The find operation geocodes one location per request; the input address can be combined into a single input field or divided among multiple parameters.
The find operation supports finding the following types of locations:
-
27488 Stanford Ave, Bowden, North Dakota380 New York St, Redlands, CA 92373
-
New York St and W Redlands Blvd, Redlands, CAJacques Veltmanstraat & Pieter Calandlaan, Amsterdam, NLD
-
Points of interest (POI) by name and type
Disneylandbanks in Parislos angeles starbucksmount everest
-
Administrative place names, such as city, county, state, province, or country names
Seattle, WashingtonState of MahārāshtraLiechtenstein
-
92591TW9 1 DN
-
-117.155579,32.703761
-
4400 Block of Perry St, Houston, Texas2400-3100 Block of San Bruno Ave, San Francisco
-
Streets between two cross streets
Conway Dr between Sheridan Ave and E El Norte Pkwy, EscondidoI-10 between exit 75 and exit 76, Redlands, CA
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
|
For more information about constructing a request, including how to choose which endpoint to use, refer to the Geocoding service overview.
There are several options for refining or restricting search results:
- Specify output fields to return in the geocoding response with the outFields parameter.
- Specify the spatial reference of candidates with the outSR parameter.
- Limit the number of candidates with the maxLocations parameter.
- Confine the search results to a specified area with the searchExtent parameter.
- Use the location parameter to prefer local candidates, which will be returned higher in the candidates list.
- Filter search results using the category parameter.
- Specify the language of geosearch candidates with the langCode parameter.
- Specify rooftop or street location for PointAddress candidates with the locationType parameter.
- Choose the type of city name or street name to be included in output fields with the preferredLabelValues parameter.
Request parameters
The find operation supports searching for places and addresses in single-field format (the Single parameter) or in multifield format with the address components separated into multiple parameters. Single-field input is easier because the address parsing is done for you; however, multifield input may provide faster responses and more precise results.
To provide a way to find addresses in many countries, which may use different addressing formats, the find operation uses standardized field names for submitting address components. In the parameters listed below, the neighborhood , city , subregion , and region parameters represent typical administrative divisions within a country. They may have different contexts for different countries, and not all administrative divisions are used in all countries. For instance, with addresses in the United States, only the city (city) and region (state) parameters are used; for addresses in Mexico, the neighborhood parameter is used for districts (colonias) within a city, city for municipalities (municipios), and the region parameter for states (estados); Spain uses all four administrative divisions.
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 parameter. For the Single input parameter, 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 parameters, such as address , address2 , address3 , city , postal , and so on, refer to the address object. Within this object, each multifield input parameter 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 parameter name. For example, information about the address parameter can be found by searching for name = address within the address object.
Required parameters
The find operation has only one required parameter: f . However, you also need to include address or place information in the request, which can be done by passing the name as a single line or as multiple fields of text. To access single-line functionality, the Single parameter is required. To access multifield functionality instead, any combination of the address , neighborhood , city , region , subregion , country , and postal parameters is required.
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=pjsontoken
The token parameter may be required; read about stored versus not stored geocoding to learn when it is required.
Use this parameter to specify a token that provides the identity of a user who has the needed permissions to access the service.
Refer to stored versus not stored geocoding for information about how to generate a token.
Example (replace <YOUR TOKEN> with a valid token)
token=<YOUR TOKEN>Optional parameters
SingleLine
The Single parameter specifies the location to be geocoded. This can be a street address, place-name, postal code, or POI. The input address components need to be formatted as a single string.
Example
SingleLine=380 New York St, Redlands, California 92373Address parameters
The full street address of a place (excluding administrative divisions and postal codes) may consist of multiple components, such as building name, street, and subunit (apartment). Web forms and written correspondence typically use multiple fields or lines to designate these components. The find operation supports three address parameters that can be used to represent the different components of a street address: address , address2 , and address3 . If you want to geocode the address Beetham Tower, 301 Deansgate, Suite 4208, Manchester, England using multiple input fields, you can set address= , address2=301 Deansgate , and address3= .
address
A string that represents the first line of a street address. In most cases, this field will be used for street name and house number input, but it can also be used to input building name or place-name.
Example of address field input in the United States
address=380 New York StreetExample of address field input in Mexico
address=Avenida Revolucion 8208address2
A string that represents the second line of a street address. This can include street name/house number, building name, place-name, or subunit.
Example address2 field input
address2=Beetham Toweraddress3
A string that represents the third line of a street address. This can include street name/house number, building name, place-name, or subunit.
Example address3 field input
address3=Suite 4208neighborhood
The smallest administrative division associated with an address, typically, a neighborhood or a section of a larger populated place. A neighborhood is a subdivision of a city.
Example of a neighborhood in Mexico (colonia)
neighborhood=Herreracity
The next largest administrative division associated with an address, typically, a city or municipality. A city is a subdivision of a subregion or a region.
Example of a city in the U.S.
city=Los AngelesExample of a city in Mexico
city=Tijuanasubregion
The next largest administrative division associated with an address. Depending on the country, a subregion can represent a county, state, or province.
Example of a subregion (department) in France
subregion=Vienneregion
The largest administrative division associated with an address, typically, a state or province.
Example of a region in the U.S. (state)
region=FloridaExample of a region in Mexico (estado)
region=Baja Californiapostal
The standard postal code for an address, typically, a three– to six-digit alphanumeric code.
Example
postal=92373postalExt
A postal code extension, such as the United States Postal Service ZIP+4 code, provides finer resolution or higher accuracy when also passing postal .
Example
postalExt=1112countryCode
A value representing the country. Providing this value increases geocoding speed. Acceptable values include the full country name in English or the official language of the country, the two-character country code, or the three-character country code. A list of supported countries and codes is available in the Data coverage topic.
Example
countryCode=USAmagicKey
The find operation retrieves results quicker when you pass in valid Single and magic values than when you don't pass in magic . However, to get these advantages, you need to make a prior request to suggest , which provides a magic . This may or may not be relevant to your workflow.
The suggest operation is often called on to improve the user experience of search boxes by analyzing partial text and providing complete names of places, addresses, points of interest, and so on. For instance, typing Mbu into a search box produces Mbuji-Mayi, Democratic Republic of the Congo as a suggestion, so the user doesn't need to type the complete name.
Looking at the suggestion process from another perspective, as the user types, the suggest operation performs a text search, which is a redundant part of the overall search that the find operation can also perform. The user chooses a place-name or type—narrowing the results to a specific record. The results from suggest include text and magic values that contain the information the user chose; passing these values from suggest into find results in faster and more accurate operations.
In summary, using the magic parameter in find is a two-step process:
- Make a request to
suggest. The response includestextandmagicproperties.Key - Make a request to
findand pass in theAddress Candidates textandmagicvalues returned fromKey suggestas theSingleandLine magicinput parameters, respectively. TheKey magicparameter will not function correctly if passed alone. BothKey magicandKey Singlemust be included in aLine findrequest so the output matches the selected suggestion.Address Candidates
Example
magicKey=JS91CYhQDS5vDPhvSMyGZby0YFbaUDoaM5bHMoFFsearchExtent
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 Search 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
}
}location
The location parameter defines an origin point that is used to prefer or boost geocoding candidates based on their proximity to the location. Candidates near the location are prioritized relative to those farther away. This is useful in mobile applications in which a user wants to search for places in the vicinity of their current GPS location, or in mapping applications in which users want to search for places near the center of the map.
The location can be represented with a simple comma-separated syntax (x,y), or as a JSON point object. If the comma-separated syntax is used, the spatial reference of the coordinates must be WGS84; otherwise, the spatial reference of the point coordinates can be defined in the JSON object.
Example using simple syntax (WGS84)
location=-117.196,34.056JSON example with a spatial reference
location=
{
"x": -13046165.572,
"y": 4036389.847,
"spatialReference": {
"wkid": 102100
}
}category
A place or address type that can be used to filter find results. The parameter supports input of single category values or multiple comma-separated values. The category parameter can be passed in a request with the Single or address parameters. It can also be passed in a request on its own without the singleline or address parameters. 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,PostaloutSR
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=102100outFields
The list of fields to be returned within the attributes object of the response. Descriptions for each of these fields are available in the Output fields section of this document.
The address , location (x,y coordinates of the match location), score , extent , and spatial objects are returned in the response by default. If the out parameter is excluded from the request, or if it is included but no fields are specified, the attributes object in the corresponding response is blank.
Example that returns all output fields
outFields=*Example that returns the specified fields only
outFields=AddNum,StName,CitymaxLocations
The maximum number of locations to be returned by a search, up to the maximum number allowed by the service. If not specified, all matching candidates up to the service maximum are returned.
The ArcGIS Geocoding service allows up to 50 candidates to be returned for a single request.
Example
maxLocations=10forStorage
The for parameter specifies whether the results of the operation will be persisted. The default value is false , which indicates the results of the operation can't be stored, but they can be temporarily displayed on a map, for instance. If you store the results, in a database, for example, you need to set this parameter to true .
Applications are contractually prohibited from storing the results of geocoding transactions unless they make the request by passing the for parameter with a value of true and the token parameter with a valid token. Instructions for composing a request with a valid token are provided in Security and authentication.
To learn more about free and paid geocoding operations, see details about stored versus not stored geocoding.
Example
forStorage=truematchOutOfRange
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 match , 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 and Subaddress 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) that 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=streetlangCode
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 find 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 find 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 find 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:
- French, German, and Italian are listed as supported languages for Switzerland. However, there is no overlap between the languages for addresses in most regions of the country. For instance, in the city of Geneva, only French addresses are available, while German is the only language used for addresses in the city of Bern.
- 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=frsourceCountry
The source parameter limits the candidates returned by the find operation to the specified country or countries. For example, if source is included in the request, it is assumed that the address is in the United States, so only matching addresses in the U.S. are returned. Using this parameter prevents potential unexpected results in other countries for ambiguous searches.
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,ESPpreferredLabelValues
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 parameter 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,primaryStreetSearch for street addresses
You can search for a street address, street name, or street intersection using the find operation. For best results, you should include as much location information as possible in the search in addition to the street address. See Match accuracy for more information about obtaining optimal results for address searches.
You can pass the address components in a single parameter or separated into multiple parameters. Examples of each are shown. Note that in each case, the JSON response is the same for both the single- and multiple-parameter requests.
Example
Find a street address (380 New York Street, Redlands, CA 92373)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=380 New York Street, Redlands, CA 92373&category=&outFields=*&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
In this example, the street address component (380 New York St) is passed as the value for the address parameter; the city component (Redlands) as the value for the city parameter; the state component (CA) as the region parameter; and the ZIP Code (92373) as the value for the postal parameter. Also in this example, all possible output fields are returned (out ), even if they don't contain a value.
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?Address=380 new york st&City=redlands&Region=CA&Postal=92373&outFields=*&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -117.195426038092,
"y": 34.056097983409
},
"score": 100,
"attributes": {
"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.056466200415,
"DisplayX": -117.195426038092,
"DisplayY": 34.056097983409,
"Xmin": -117.196426038092,
"Xmax": -117.194426038092,
"Ymin": 34.055097983409,
"Ymax": 34.057097983409,
"ExInfo": "",
"StrucType": "Commercial",
"StrucDet": "Office"
},
"extent": {
"xmin": -117.196426038092,
"ymin": 34.055097983409,
"xmax": -117.194426038092,
"ymax": 34.057097983409
}
}
]
}Search for intersections
An intersection is where two streets cross each other. An intersection search consists of the intersecting street names plus the containing administrative division or postal code. For example, redlands blvd and new york st 92373 is a valid intersection search, as is redlands blvd & new york st redlands ca . For street intersection matches, Addr .
Standard intersections
There are several types of intersections that can found by the ArcGIS Geocoding service. A typical simple intersection is formed by two street segments crossing each other. An example of this is W Park Ave and Tennessee St, Redlands, CA .
Example
Find a simple street intersection (W Park Ave and Tennessee St, Redlands, CA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&SingleLine=W Park Ave and Tennessee St, Redlands, CA&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&Address=W Park Ave and Tennessee St&City=Redlands&Region=CA&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "W Park Ave & Tennessee St, Redlands, California, 92373",
"location": {
"x": -117.200080508925,
"y": 34.059249411365
},
"score": 100,
"attributes": {
"Addr_type": "StreetInt"
},
"extent": {
"xmin": -117.201080508925,
"ymin": 34.058249411365,
"xmax": -117.199080508925,
"ymax": 34.060249411365
}
}
]
}Overpass intersections
You can also find intersections between streets that aren't physically connected. This includes cases where streets are separated by elevation, such as a highway overpass crossing over another street. An example of this is Pacific Hwy and W Washington St, San Diego, C .
Example
Find an intersection at a highway overpass (Pacific Hwy and W Washington St, San Diego, CA 92140)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&SingleLine=Pacific Hwy and W Washington St, San Diego, CA 92140&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&Address=Pacific Hwy and W Washington St&City=San Diego&Region=CA&Postal=92140&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Pacific Hwy & W Washington St, San Diego, California, 92140",
"location": {
"x": -117.184382796839,
"y": 32.740451997491
},
"score": 100,
"attributes": {
"Addr_type": "StreetInt"
},
"extent": {
"xmin": -117.185382796839,
"ymin": 32.739451997491,
"xmax": -117.183382796839,
"ymax": 32.741451997491
}
}
]
}Disconnected intersections
An intersection can also be formed by two disconnected streets when one street ends close to another, such as a cul-de-sac or a dead end. In cases such as this, if the streets are within a certain distance of each other, the ArcGIS Geocoding service returns a StreetInt match when they are searched for. This near-intersection tolerance is currently 60 meters. An example of this type of near-intersection is Knowlton St and Turner Ct, Somerville, Massachusetts, USA .
Example
Find a near-intersection (Knowlton St and Turner Ct, Somerville, Massachusetts, USA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&SingleLine=Knowlton St and Turner Ct, Somerville, Massachusetts, USA&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&Address=Knowlton St and Turner Ct&City=Somerville&Region=Massachusetts&CountryCode=USA&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Knowlton St & Turner Ct, Somerville, Massachusetts, 02145",
"location": {
"x": -71.086933487601,
"y": 42.382329186603
},
"score": 100,
"attributes": {
"Addr_type": "StreetInt"
},
"extent": {
"xmin": -71.087933487601,
"ymin": 42.381329186603,
"xmax": -71.085933487601,
"ymax": 42.383329186603
}
}
]
}Roundabout intersections
Another type of disconnected intersection supported by the ArcGIS Geocoding service occurs at roundabouts. A roundabout is formed when two or more streets connect to a circular roadway, which is often unnamed. The participating streets typically don't connect directly to each other, but when they are searched for and are within the near-intersection tolerance, the service returns a StreetInt match. An example of a roundabout intersection is Rue Jean Laurent & Avenue Jean Mermoz, Le Vésinet, FRA .
Example
Find a roundabout intersection (Rue Jean Laurent & Avenue Jean Mermoz, Le Vésinet, FRA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&SingleLine=Rue Jean Laurent and Avenue Jean Mermoz, Le Vésinet, FRA&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&Address=Rue Jean Laurent & Avenue Jean Mermoz&City=Le Vésinet&CountryCode=FRA&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Rue Jean Laurent & Avenue Jean Mermoz, 78110, Le Vésinet, Yvelines, Île-de-France",
"location": {
"x": 2.134517483476,
"y": 48.895231987767
},
"score": 100,
"attributes": {
"Addr_type": "StreetInt"
},
"extent": {
"xmin": 2.133517483476,
"ymin": 48.894231987767,
"xmax": 2.135517483476,
"ymax": 48.896231987767
}
}
]
}Ambiguous intersections
Sometimes there may be multiple possible matches for an intersection search. This typically occurs when divided roads cross each other. A divided road consists of two street segments separated by a median. In a scenario such as this, there could be up to four equivalent intersection matches consisting of the same street names at different locations. The ArcGIS Geocoding service uses an ambiguous intersection tolerance with such searches to remove redundant intersection candidates from the response. The ambiguous intersection tolerance is currently 30 meters. Specifically, if there are multiple intersection candidates with the same street names that are located in the same locality (meaning same neighborhood, city, postal code), and if they are within 30 meters of each other, the service returns only one of the candidates.
An example of an ambiguous intersection search is Cambie St and W King Edward Ave, Vancouver, British Columbia . Both Cambie St and W King Edward Ave are divided streets, so there are four potential intersection candidates with the same street names. However, there is a boundary between the neighborhoods of South Cambie and Riley Park which happens to follow the middle of Cambie St. Because of this, there are actually two sets of equivalent intersections—one within South Cambie (on left side of Cambie St) and the other within Riley Park (on the right side of Cambie St). The locations of the potential intersection candidates in each set are within the ambiguous intersection distance from each other, so two intersection candidates are returned in the response for this search—one in South Cambie, and the other in Riley Park.
Example
Find an ambiguous intersection (Cambie St and W King Edward Ave, Vancouver, British Columbia)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type,Nbrhd&forStorage=false&SingleLine=Cambie St and W King Edward Ave, Vancouver, British Columbia&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type,Nbrhd&forStorage=false&Address=Cambie St and W King Edward Ave&City=Vancouver&Region=British Columbia&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Cambie St & King Edward Ave W, Vancouver, British Columbia, V5Z",
"location": {
"x": -123.115292006692,
"y": 49.248915989533
},
"score": 99.96,
"attributes": {
"Addr_type": "StreetInt",
"Nbrhd": "Riley Park"
},
"extent": {
"xmin": -123.116292006692,
"ymin": 49.247915989533,
"xmax": -123.114292006692,
"ymax": 49.249915989533
}
},
{
"address": "Cambie St & King Edward Ave W, Vancouver, British Columbia, V5Z",
"location": {
"x": -123.115300891509,
"y": 49.249055967317
},
"score": 99.96,
"attributes": {
"Addr_type": "StreetInt",
"Nbrhd": "Riley Park"
},
"extent": {
"xmin": -123.116300891509,
"ymin": 49.248055967317,
"xmax": -123.114300891509,
"ymax": 49.250055967317
}
},
{
"address": "Cambie St & King Edward Ave W, Vancouver, British Columbia, V5Z",
"location": {
"x": -123.115498033872,
"y": 49.248924036161
},
"score": 99.96,
"attributes": {
"Addr_type": "StreetInt",
"Nbrhd": "South Cambie"
},
"extent": {
"xmin": -123.116498033872,
"ymin": 49.247924036161,
"xmax": -123.114498033872,
"ymax": 49.249924036161
}
}Search for POIs
In the context of the ArcGIS Geocoding service, a POI is a point location that can represent a cultural or geographic landmark, business, or administrative division. For example, you can find amusement parks, museums, schools, restaurants, hotels, gas stations, or other types of businesses or landmarks; geographic features, such as mountains, lakes, rivers, or deserts; or administrative places, such as neighborhoods, cities, states, counties, or countries. The find operation supports geocoding POIs by name or by type.
As with street addresses, you can search for POIs with find 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 or type> <optional connector> <zone>
- <zone> <name or type>
- <name or type><address><zone>
Where
- <name or type> = A place-name, such as Disneyland, Starbucks, or Niagara Falls; or a type, such as amusement parks, waterfalls, or coffee shops.
- <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
Type searches
- coffee shops San Diego
- coffee shops in San Diego CA
- San Diego coffee shops
- coffee shops 92101
- coffee shops 5th Ave San Diego
Multifield POI search
When searching for POIs using multifield input, the name or type 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.
General information
It is important to note that instead of providing a zone, you can limit searches to a specific area by using the search parameter. You can also influence the sorting of match candidates according to their proximity to a location with the location parameter.
As with address searches, the quality of POI search results is dependent on the amount and quality of information in the search string. If you only search for hotels without qualifying information, such as zone, search extent, or location, your results will not be meaningful. Adding supplemental information to the search string—the more specific, the better—will result in more accurate and relevant matches.
Example
Find a business name (Starbucks Sydney, AUS)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=starbucks sydney AUS&outFields=type,city,region&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?Address=starbucks&Neighborhood=&City=sydney&Subregion=&Region=&CountryCode=AUS&outFields=type,city,region&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Starbucks",
"location": {
"x": 151.249914,
"y": -33.891673
},
"score": 100,
"attributes": {
"type": "Coffee Shop",
"city": "Sydney",
"region": "New South Wales"
},
"extent": {
"xmin": 151.244914,
"ymin": -33.896673,
"xmax": 151.254914,
"ymax": -33.886673
}
}
]
}Example
Find a business type (hotels Orlando, FL)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=hotels orlando FL&outFields=type,city,region&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Bay Lake Tower At Disney's Contemporary Resort",
"location": {
"x": -81.5736337,
"y": 28.4164133
},
"score": 100,
"attributes": {
"type": "Hotel",
"city": "Orlando",
"region": "Florida"
},
"extent": {
"xmin": -81.5786337,
"ymin": 28.4114133,
"xmax": -81.5686337,
"ymax": 28.4214133
}
}Example
Find a business on a specific street (Starbucks 5th Ave San Diego)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=starbucks 5th ave san diego&langCode=&outFields=Place_Name,Place_addr,Phone,Type,Addr_type&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=starbucks&address2=5th ave&city=san diego&outFields=Place_Name,Place_addr,Phone,Type,Addr_type&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Starbucks",
"location": {
"x": -117.160236,
"y": 32.747095
},
"score": 100,
"attributes": {
"Addr_type": "POI",
"Type": "Coffee Shop",
"Place_addr": "3801 5th Ave, San Diego, California, 92103",
"Phone": "(619) 295-9310"
},
"extent": {
"xmin": -117.161236,
"ymin": 32.746095,
"xmax": -117.159236,
"ymax": 32.748095
}
},
{
"address": "Starbucks",
"location": {
"x": -117.159905,
"y": 32.707766
},
"score": 100,
"attributes": {
"Addr_type": "POI",
"Type": "Coffee Shop",
"Place_addr": "209 5th Ave, San Diego, California, 92101",
"Phone": "(619) 234-0749"
},
"extent": {
"xmin": -117.160905,
"ymin": 32.706766,
"xmax": -117.158905,
"ymax": 32.708766
}
},
{
"address": "Starbucks",
"location": {
"x": -117.160486,
"y": 32.731103
},
"score": 100,
"attributes": {
"Addr_type": "POI",
"Type": "Coffee Shop",
"Place_addr": "2440 5th Ave, San Diego, California, 92101",
"Phone": "(619) 702-2113"
},
"extent": {
"xmin": -117.161486,
"ymin": 32.730103,
"xmax": -117.159486,
"ymax": 32.732103
}
}
]
}Search for administrative place-names
The find operation supports single-field and multifield searches for administrative place-names. This includes searches for neighborhoods, cities, counties, states, provinces, or countries. If a search for a city name results in multiple matches with the same name, the ArcGIS Geocoding service will sort the candidates in order of their relative importance to each other (as indicated by the value of the Rank output field), with priority generally based on population and capital status. For example, there are many cities in the world named San Francisco, so a search for San Francisco results in several equivalent matches; San Francisco, California, USA, will always be the top candidate since it has the greatest population.
Example
Find a city name (San Francisco)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=San Francisco&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=San Francisco&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "San Francisco, California",
"location": {
"x": -122.4201615,
"y": 37.7800771
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": -122.7151615,
"ymin": 37.4850771,
"xmax": -122.1251615,
"ymax": 38.0750771
}
},
{
"address": "San Francisco, Agusan Del Sur, Caraga",
"location": {
"x": 125.978219,
"y": 8.5025332
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": 125.856219,
"ymin": 8.3805332,
"xmax": 126.100219,
"ymax": 8.6245332
}
}However, rank alone is not always enough to distinguish between administrative places. Also, you may not necessarily want to find the highest-ranked feature for a particular search. It may be necessary to remove ambiguity by refining searches with additional information. For example, a search for Oxford returns Oxford, UK, as the top candidate based on rank. If you instead want to find the town of Oxford, Ohio, it is necessary to add the state information to the search.
Example
Search for city, state (Oxford, OH)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=oxford OH&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=Oxford®ion=OH&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Oxford, Ohio",
"location": {
"x": -84.7456597,
"y": 39.5073941
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": -84.7976597,
"ymin": 39.4553941,
"xmax": -84.6936597,
"ymax": 39.5593941
}
}Search for postal codes
The find operation supports searches for postal codes and postal code extensions. When searching for postal codes, it is important to note that the same code can be valid in more than one country; for best results, it may be necessary to include additional information with the postal code, such as city or country.
Example
Find a postal code (20002 USA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=20002 USA&forStorage=false&outFields=addr_type&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?postal=20002&countryCode=USA&outFields=addr_type&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "20002, Washington, District of Columbia",
"location": {
"x": -76.9927743,
"y": 38.9042588
},
"score": 100,
"attributes": {
"addr_type": "Postal"
},
"extent": {
"xmin": -77.0177743,
"ymin": 38.8792588,
"xmax": -76.9677743,
"ymax": 38.9292588
}
}
]
}Search for coordinates
The ArcGIS Geocoding service supports searches for coordinates. 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 coordinate search are supported:
- 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
MGRS and USNG coordinates can be searched with various precisions, from 10,000-meter square to 1-meter square precision. See the table below for examples of valid MGRS or USNG search input.
MGRS/USNG examples
18SUH64 | 10,000-meter square | 2-digit coordinate |
18SUH6743 | 1,000-meter square | 4-digit coordinate |
18SUH678432 | 100-meter square | 6-digit coordinate |
18SUH67894321 | 10-meter square | 8-digit coordinate |
18SUH6789043210 | 1-meter square | 10-digit coordinate |
Example
Find MGRS / USNG coordinates (18SUH6789043210)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&maxLocations=1&forStorage=false&SingleLine=18SUH6789043210&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&maxLocations=1&forStorage=false&Address=18SUH6789043210&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "18SUH6789043210",
"location": {
"x": -76.511416672563,
"y": 38.327287449633
},
"score": 100,
"attributes": {
"Addr_type": "MGRS"
},
"extent": {
"xmin": -76.512416672563,
"ymin": 38.326287449633,
"xmax": -76.510416672563,
"ymax": 38.328287449633
}
}
]
}Input x,y coordinates can be formatted in several ways:
-
Coordinates can be input in either <longitude>,<latitude> or <latitude>,<longitude> order, and can be separated with either a comma or a space.
-
Coordinates can be input in decimal degrees (DD) or degrees minutes seconds (DMS) format.
-
Quadrants can be signified by using a minus sign (-) before the numeric value to signify the western or southern quadrants, or by using E, W, N, or S directional indicators before or after the numeric values.
-
DMS coordinates can be separated with ° (degrees), ' (minutes), and " (seconds) symbols.
-
DMS coordinates can also be separated with the letters
d(degrees),m(minutes), ands(seconds).
The following tables shows examples of different formats that can be used to search x,y coordinates.
Decimal degrees examples
| Longitude | Latitude | Example search input |
|---|---|---|
-14 | 28.4 | -14 28.4 |
14 W | 28.4 N | 45 W, 45 N |
14.09W | 28.37N | 14.09W 28.37N |
W14 | N28.4 | W14, N28.4 |
X: -14 | Y: 28.4 | X: -14 Y: 28.4 |
-14.079085 | 28.413518 | -14.079085, 28.413518 |
Degrees minutes seconds examples
| Longitude | Latitude | Example search input |
|---|---|---|
14°05'20" W | 28°25'01" N | 14°05'20" W 28°25'01" N |
-14°05'20" | 28°25'01" | -14°05'20",28°25'01" |
X:-14°05'20" | Y:28°25'01" | X:-14°05'20" Y:28°25'01" |
14° 05' 20" W | 28° 25' 01" N | 14° 05' 20" W 28° 25' 01" N |
14d05m20s W | 28d25m01s N | 14d05m20s W 28d25m01s N |
-14d05m20s | 28d25m01s | -14d05m20s,28d25m01s |
X:-14d05m20s | Y:28d25m01s | X:-14d05m20s Y:28d25m01s |
14d 05m 20s W | 28d 25m 01s N | 14d 05m 20s W 28d 25m 01s N |
Searches for x,y coordinates can be ambiguous, because some users may place the longitude (x) coordinate first, while others may place the latitude (y) coordinate first. For instance, a search for x,y coordinates 80,50 produces very different results when longitude is first than when latitude is first. The service handles this by returning candidates in both <latitude and <longitude formats for ambiguous coordinate searches. The ArcGIS Geocoding service returns two or three candidates with the following possible Addr values for x,y coordinate searches:
Lat—Returned when the first coordinate in the input is either explicitly or implicitly determined to be the longitude coordinate. The correspondingLong Matchvalue is formatted as_addr <longitude, such as> <latitude > 10.000000 50.000000.XY—Returned when the first coordinate in the input is either explicitly or implicitly determined to be the longitude coordinate. The correspondingMatchvalue is formatted as_addr X, such as:<longitude > Y :<latitude > X.:10.000000 Y :50.000000 YX—Returned when the first coordinate in the input is either explicitly or implicitly determined to be the latitude coordinate. The correspondingMatchvalue is formatted as_addr Y, such as:<latitude > X :<longitude > Y.:50.000000 X :10.000000
Details about the logic used by the service for x,y coordinate searches are listed below.
- For ambiguous x,y searches in which both input coordinates are valid as either latitude or longitude, three candidates are returned, one for each of the
Addrvalues listed above. Example—_type 10,50 - For x,y searches in which the longitude and latitude coordinates are explicitly defined by X/Y or directional (N, S, E, W) indicators, and the longitude value precedes the latitude value,
LatandLong XYcandidates are returned. Example—10orW,50 N X:10, Y :50 - For x,y searches in which the longitude and latitude coordinates are explicitly defined by X/Y or directional (N, S, E, W) indicators, and the latitude value precedes the longitude value, only a
YXcandidate is returned. Example—50orN,10 W Y:50, X :10 - If one of the input coordinates is outside the valid range of latitude values and the service can implicitly determine that it is the longitude, and the longitude value precedes the latitude value,
LatandLong XYcandidates are returned. Example—-120,50 - If one of the input coordinates is outside the valid range of latitude values and the service can implicitly determine that it is the longitude, and the latitude value precedes the longitude value, only a
YXcandidate is returned. Example—50,-120
Example
Find an ambiguous x,y coordinate pair (18.9919543,47.5283605)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?ff=pjson&outFields=Addr_type&maxLocations=3&forStorage=false&SingleLine=18.9919543,47.5283605&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?ff=pjson&outFields=Addr_type&maxLocations=3&forStorage=false&address=18.9919543,47.5283605&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "18.991954 47.528360",
"location": {
"x": 18.9919543,
"y": 47.528360499999998
},
"score": 100,
"attributes": {
"Addr_type": "LatLong"
},
"extent": {
"xmin": 18.990954299999999,
"ymin": 47.5273605,
"xmax": 18.992954300000001,
"ymax": 47.529360499999996
}
},
{
"address": "X:18.991954 Y:47.528360",
"location": {
"x": 18.9919543,
"y": 47.528360499999998
},
"score": 100,
"attributes": {
"Addr_type": "XY"
},
"extent": {
"xmin": 18.990954299999999,
"ymin": 47.5273605,
"xmax": 18.992954300000001,
"ymax": 47.529360499999996
}
},
{
"address": "Y:18.991954 X:47.528360",
"location": {
"x": 47.528360499999998,
"y": 18.9919543
},
"score": 100,
"attributes": {
"Addr_type": "YX"
},
"extent": {
"xmin": 47.5273605,
"ymin": 18.990954299999999,
"xmax": 47.529360499999996,
"ymax": 18.992954300000001
}
}
]
}Example
Find an explicit latitude/longitude coordinate pair (Y:47.5283605 X:18.9919543)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&SingleLine=Y:47.5283605 X:18.9919543&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&forStorage=false&address=Y:47.5283605 X:18.9919543&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Y:47.528360 X:18.991954",
"location": {
"x": 18.9919543,
"y": 47.5283605
},
"score": 100,
"attributes": {
"Addr_type": "YX"
},
"extent": {
"xmin": 18.9909543,
"ymin": 47.5273605,
"xmax": 18.9929543,
"ymax": 47.5293605
}
}
]
}Example
Find an implicit longitude/latitude coordinate pair (151.214776,-33.856716)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&maxLocations=2&forStorage=false&SingleLine=151.214776,-33.856716&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?f=pjson&outFields=Addr_type&maxLocations=2&forStorage=false&address=151.214776,-33.856716&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "151.214776 -33.856716",
"location": {
"x": 151.214776,
"y": -33.856716
},
"score": 100,
"attributes": {
"Addr_type": "LatLong"
},
"extent": {
"xmin": 151.213776,
"ymin": -33.857716,
"xmax": 151.215776,
"ymax": -33.855716
}
},
{
"address": "X:151.214776 Y:-33.856716",
"location": {
"x": 151.214776,
"y": -33.856716
},
"score": 100,
"attributes": {
"Addr_type": "XY"
},
"extent": {
"xmin": 151.213776,
"ymin": -33.857716,
"xmax": 151.215776,
"ymax": -33.855716
}
}
]
}Search for street blocks
The find operation supports searches for a group of house numbers representing one or more city blocks. The Addr value returned for this type of search is StreetMidBlock. The location of such a feature is the approximated midpoint of the street segments that include the house numbers represented by the block number or block range. A StreetMidBlock match is more precise than a StreetName match, and less precise than a StreetAddress match.
A single block, or a range of blocks, may be searched for. Here are some examples of StreetMidBlock searches:
- 100 block of New York St, Redlands, CA
- 1600 blk E Cliff Dr, El Paso
- 200-500 block Taylor St, San Francisco
- 1700-1900 blk of Locust St, Philadelphia, Pennsylvania
For a StreetMidBlock match to be returned, the input text must follow this general syntax:
<number or range block | block of <street name
StreetMidBlock matching is useful for situations in which an exact address is unknown, such as emergency reporting. For example, a bystander witnessing an emergency may know the name of the street they're on and the general house numbers in their vicinity, but not the exact house number—emergency responders can use the block information to quickly find the approximate location of the incident.
It's also useful for workflows in which anonymity is required for privacy concerns, such as crime data analysis by law enforcement agencies. In such cases, when law enforcement personnel respond to an incident, the street block where the incident occurred can be recorded instead of a person's complete address.
Example
Find a single block number (100 block of New York St, Redlands, CA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=100 block of New York St, Redlands, CA&outFields=Addr_type&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=100 block of New York St&city=San Francisco&outFields=addr_type&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "100 Block of New York St, Redlands, California, 92373",
"location": {
"x": -117.195624321099,
"y": 34.054132171282
},
"score": 100,
"attributes": {
"Addr_type": "StreetMidBlock"
},
"extent": {
"xmin": -117.196567077114,
"ymin": 34.052789858379,
"xmax": -117.194556366429,
"ymax": 34.055594477321
}
}Example
Find a range of blocks (200-500 block Taylor St, San Francisco)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=200-500 block Taylor St, San Francisco&outFields=Addr_type&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=200-500 block Taylor St&city=San Francisco&outFields=addr_type&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "200-500 Block of Taylor St, San Francisco, California, 94102",
"location": {
"x": -122.411532161018,
"y": 37.78699720641
},
"score": 100,
"attributes": {
"Addr_type": "StreetMidBlock"
},
"extent": {
"xmin": -122.412460493737,
"ymin": 37.78600586109,
"xmax": -122.410460493737,
"ymax": 37.78800586109
}
}Search for a street between two cross streets
The find operation supports searching for a street between two intersecting cross streets. The Addr value returned for this type of search is StreetBetween. The location of such a feature is along the matched street at the midpoint between the cross streets. The precision of a StreetBetween match is greater than a StreetName match, less than a StreetAddress match, and equal to a StreetMidBlock match.
Here are some examples of StreetBetween searches:
- Conway Dr between Sheridan Ave and E El Norte Pkwy, Escondido, CA
- I-10 bt exit 75 and exit 76, Redlands, CA
- Pinckney btw Joy & Anderson, Boston
For a StreetBetween match to be returned, the input text must follow this general syntax:
<street name between | btw | bt <cross street 1 and <cross street 2
Similar to StreetMidBlock, StreetBetween matching is useful for situations in which an exact address or location is unknown, such as emergency reporting. For example, a person involved in an incident may know the name of the street they're on and the nearby intersecting streets but not an exact address—emergency responders can use this information to quickly find the approximate location of the incident.
Example
Find a street between two cross streets (Conway Dr between Sheridan Ave and E El Norte Pkwy, Escondido, CA)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleline=Conway Dr between Sheridan Ave and E El Norte Pkwy, Escondido, CA&outFields=Addr_type&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=Conway Dr between Sheridan Ave and E El Norte Pkwy&city=Escondido®ion=CA&outFields=Addr_type&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Conway Dr between Sheridan Ave and E El Norte Pkwy, Escondido, California, 92027",
"location": {
"x": -117.074761248522,
"y": 33.147567713195
},
"score": 100,
"attributes": {
"Addr_type": "StreetBetween"
},
"extent": {
"xmin": -117.075761248522,
"ymin": 33.146567713195,
"xmax": -117.073761248522,
"ymax": 33.148567713195
}
}Specify output fields
The find operation allows you to specify individual output fields or return all output fields. The out parameter is used for this. If you want to return all supported output fields, set out ; if you only want to return the default output fields, out does not need to be passed in the request. If you want to return specific fields, pass the desired field names as comma-separated values, such as out , which returns the name, feature type, city, and country for a POI search.
See Service output for details about the fields returned by a find request.
Example
Specify individual outfields for a POI search (PlaceName,Type,City,Country)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=coffee shops austin&outFields=PlaceName,Type,City,Country&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Caribou Coffee",
"location": {
"x": -92.985396,
"y": 43.684369
},
"score": 100,
"attributes": {
"Type": "Coffee Shop",
"PlaceName": "Caribou Coffee",
"City": "Austin",
"Country": "USA"
},
"extent": {
"xmin": -92.986396,
"ymin": 43.683369,
"xmax": -92.984396,
"ymax": 43.685369
}
}Specify the output spatial reference
By default, the ArcGIS Geocoding service returns candidate geometry in WGS84 coordinates (decimal degrees). You can specify a different spatial reference for output coordinates by using the out parameter. This is necessary if you have a mapping application in which you display geocoding candidates and the map spatial reference is not WGS84. For example, the ArcGIS.com basemaps use a Web Mercator spatial reference, with coordinates in meters. To display geocoding candidates correctly in such a map, you would need to set out , which is the well-known ID (WKID) of the Web Mercator spatial reference.
For a list of valid WKID values, see Projected coordinate systems and Geographic coordinate systems.
Example
Specify output coordinates in Web Mercator spatial reference (380 new york st redlands ca)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?SingleLine=380 new york st redlands ca&outSR=102100&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=380 new york st&city=redlands®ion=ca&outSR=102100&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 102100,
"latestWkid": 3857
},
"candidates": [
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -13046135.1498611271,
"y": 4036337.10429923097
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": -13046246.4693519212,
"ymin": 4036202.74072433496,
"xmax": -13046023.830370333,
"ymax": 4036471.46945925895
}
}
]
}Specify the maximum number of candidates
The max parameter allows you to specify the maximum number of candidates to be returned by a search, up to the maximum number of candidates allowed by the ArcGIS Geocoding service. By default, the service allows up to 50 candidates to be returned for searches. As an example, if you set max , find will return the top 10 candidates for the search. If no value is specified for max , find returns all matching candidates.
Example
Specify the maximum number of candidates for a POI search (Starbucks in Redlands)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=starbucks in redlands&outFields=PlaceName,City,Country&maxLocations=2&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=starbucks&city=redlands&outFields=PlaceName,City,Country&maxLocations=2&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Starbucks",
"location": {
"x": -117.225684,
"y": 34.049181
},
"score": 100,
"attributes": {
"PlaceName": "Starbucks",
"City": "Redlands",
"Country": "USA"
},
"extent": {
"xmin": -117.226684,
"ymin": 34.048181,
"xmax": -117.224684,
"ymax": 34.050181
}
},
{
"address": "Starbucks",
"location": {
"x": -117.204248,
"y": 34.07144
},
"score": 100,
"attributes": {
"PlaceName": "Starbucks",
"City": "Redlands",
"Country": "USA"
},
"extent": {
"xmin": -117.205248,
"ymin": 34.07044,
"xmax": -117.203248,
"ymax": 34.07244
}
}
]
}Search within an extent
The find 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. Bounding rectangle coordinates can be entered as a simple comma-separated string in the format <lower left corner>,<upper right corner>. If the simple format is used, 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 find McDonald's in downtown San Diego using the search format.
Example
Find POIs using search with default spatial reference (McDonald's)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=mcdonalds&outFields=city,type&searchExtent=-117.172026,32.706517,-117.152498,32.725514&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=mcdonalds&outFields=city,type&searchExtent=-117.172026,32.706517,-117.152498,32.725514&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "McDonald's",
"location": {
"x": -117.158742,
"y": 32.71242
},
"score": 100,
"attributes": {
"type": "Fast Food",
"city": "San Diego"
},
"extent": {
"xmin": -117.159742,
"ymin": 32.71142,
"xmax": -117.157742,
"ymax": 32.71342
}
},
{
"address": "McDonald's",
"location": {
"x": -117.154059,
"y": 32.718697
},
"score": 100,
"attributes": {
"type": "Fast Food",
"city": "San Diego"
},
"extent": {
"xmin": -117.155059,
"ymin": 32.717697,
"xmax": -117.153059,
"ymax": 32.719697
}
}
]
}You can specify a spatial reference for the search , which is necessary if your map uses a different spatial reference than the geocode service. For example, the default ArcGIS.com basemaps use a Web Mercator spatial reference (WKID = 102100), with coordinates in meters. The search must be passed as a JSON envelope object if the coordinates are in a spatial reference other than WGS84. The following request URL uses the previous example of McDonald's in downtown San Diego, but specifies the bounding rectangle with Web Mercator coordinates.
Example
Find POIs using search with Web Mercator spatial reference (McDonald's)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=mcdonalds&outFields=City,Type&searchExtent={"xmin":-13043558,"ymin":3856395,"xmax":-13041325,"ymax":3858918,"spatialReference":{"wkid":102100}}&outSR=102100&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=mcdonalds&outFields=City,Type&searchExtent={"xmin":-13043558,"ymin":3856395,"xmax":-13041325,"ymax":3858918,"spatialReference":{"wkid":102100}}&outSR=102100&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 102100,
"latestWkid": 3857
},
"candidates": [
{
"address": "McDonald's",
"location": {
"x": -13042051.5014205072,
"y": 3857194.44405129505
},
"score": 100,
"attributes": {
"Type": "Fast Food",
"City": "San Diego"
},
"extent": {
"xmin": -13042162.8209113032,
"ymin": 3857062.14109622128,
"xmax": -13041940.1819297168,
"ymax": 3857326.74848951353
}
},
{
"address": "McDonald's",
"location": {
"x": -13041530.1922451239,
"y": 3858024.9435766032
},
"score": 100,
"attributes": {
"Type": "Fast Food",
"City": "San Diego"
},
"extent": {
"xmin": -13041641.511735918,
"ymin": 3857892.63131060777,
"xmax": -13041418.8727543298,
"ymax": 3858157.25732620433
}
}
]
}Requests that include search can also include zone information (that is, city, state, and country). If the extent defined for search is large enough to encompass multiple cities, it may be necessary to include the city name in the search to achieve optimal results. For example, if the search covers the Dallas-Fort Worth metropolitan region, and you search for Starbucks , there could be matches returned in Dallas or Fort Worth or any of their suburbs. If you specifically want to find Starbucks in Garland, for example, this needs to be specified in the search.
Example
Find POIs using search and zone (Starbucks garland)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=starbucks garland&outFields=type,city,region&searchExtent=-97.407282,32.416436,-96.537829,33.141819&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=starbucks&city=garland&outFields=type,city,region&searchExtent=-97.407282,32.416436,-96.537829,33.141819&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Starbucks",
"location": {
"x": -96.66027,
"y": 32.864458
},
"score": 100,
"attributes": {
"type": "Coffee Shop",
"city": "Garland",
"region": "Texas"
},
"extent": {
"xmin": -96.66127,
"ymin": 32.863458,
"xmax": -96.65927,
"ymax": 32.865458
}
}You can also search for street addresses within an extent. When the search parameter is defined for an address search, city and postal code can be omitted from the search and valid matches can still be found. However, if the search is large, it is possible for a street address to occur multiple times within the extent, and it may be necessary to refine the search by including city, state, postal code, or other distinguishing information. Additionally, if the search includes a city or postal code that is outside the search , no matches will be returned. See the following example, which illustrates finding a street address using search .
Example
Find a street address using search (380 New York St)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=380 new york st&searchExtent=-117.225635,34.015757,-117.119866,34.087402&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=380 new york st&searchExtent=-117.225635,34.015757,-117.119866,34.087402&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "380 New York St, Redlands, California, 92373",
"location": {
"x": -117.195426038092,
"y": 34.056097983409
},
"score": 100,
"attributes": {
},
"extent": {
"xmin": -117.196426038092,
"ymin": 34.055097983409,
"xmax": -117.194426038092,
"ymax": 34.057097983409
}
}
]
}Proximity searches
Geocoding results are typically sorted according to their relevance to the search and their relative importance. However, with some applications, especially mobile apps, users are more concerned with finding features closest to their current location. For this reason, the find operation supports prioritization of candidates based on their distance from a specified point. By passing in the location parameter, you can define an area of influence for your searches. The location value represents the center point of the area, which spans a radius of 50,000 meters. Features closest to the input location show up higher in the list of candidates. Results that are within the area of influence area receive a greater boost than those outside the area.
It is important to note that proximity search does not filter results that are farther than 50,000 meters from the input location—it is intended to influence the sort order of results so the most locationally relevant candidates are returned first. For instance, if your location is in Las Vegas, and you search for Bellagio, the first candidate is Bellagio in Las Vegas. The second candidate is in a different part of the United States, much farther away than 50,000 meters, but is still returned because it is the second most relevant (closest) candidate. In general, the number of candidates returned by a proximity search is only limited by the max parameter.
Example
Find a place name using a proximity search (Bellagio)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=bellagio&outFields=City,Region,Country&maxLocations=10&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=bellagio&outFields=City,Region,Country&maxLocations=10&location=-115.172783,36.114789&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Bellagio",
"location": {
"x": -115.1762689,
"y": 36.1131468
},
"score": 100,
"attributes": {
"City": "Las Vegas",
"Region": "Nevada",
"Country": "USA"
},
"extent": {
"xmin": -115.1812689,
"ymin": 36.1081468,
"xmax": -115.1712689,
"ymax": 36.1181468
}
},
{
"address": "Bellagio, Calabasas, California",
"location": {
"x": -118.6349961,
"y": 34.1439143
},
"score": 100,
"attributes": {
"City": "Calabasas",
"Region": "California",
"Country": "USA"
},
"extent": {
"xmin": -118.6379961,
"ymin": 34.1409143,
"xmax": -118.6319961,
"ymax": 34.1469143
}
}If you only want to return candidates within a specific area, and sort the candidates according to their proximity to a location, you need to define a search extent by passing the search parameter in the request along with the location parameter. Consider the Golden Nugget example again. If your location is in Las Vegas and you want to confine your search results to places named Golden Nugget that are within the map extent, you would need to construct a request with the following parameters:
Single(orLine address): Bellagiolocation: -115.172783,36.114789search: -115.2568,36.045626,-115.07759,36.1904Extent
The request URL would be similar to the one below. See the Search within an extent section above for more information about the search parameter.
Example
Find a place-name using both proximity and search (Bellagio)
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=bellagio&outFields=City,Region,Country&searchExtent=-115.2568,36.045626,-115.07759,36.1904&location=-115.172783,36.114789&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=bellagio&outFields=City,Region,Country&searchExtent=-115.2568,36.045626,-115.07759,36.1904&location=-115.172783,36.114789&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "Bellagio",
"location": {
"x": -115.1762689,
"y": 36.1131468
},
"score": 100,
"attributes": {
"City": "Las Vegas",
"Region": "Nevada",
"Country": "USA"
},
"extent": {
"xmin": -115.1812689,
"ymin": 36.1081468,
"xmax": -115.1712689,
"ymax": 36.1181468
}
}
]
}Category filtering
The find operation supports filtering searches by category values, which represent address and place types. By including the category parameter in a find request, you can avoid false positive matches to unexpected place and address types due to ambiguous searches.
For example, a user may search for June, expecting the service to match to June Mountain ski resort. However, there are many places in the world named June, so the search returns several cities named June.
Example
Search for "June" without a category
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=June&category=&outFields=PlaceName,Type,Place_Addr,City,Region&maxLocations=5&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "June, Missouri",
"location": {
"x": -94.360217,
"y": 36.80118
},
"score": 100,
"attributes": {
"Type": "Village",
"PlaceName": "June",
"Place_Addr": "June, Missouri",
"City": "June",
"Region": "Missouri"
},
"extent": {
"xmin": -94.367217,
"ymin": 36.79418,
"xmax": -94.353217,
"ymax": 36.80818
}
},
{
"address": "June, Lacombe County, Alberta",
"location": {
"x": -113.603535729,
"y": 52.482597831
},
"score": 100,
"attributes": {
"Type": "Village",
"PlaceName": "June",
"Place_Addr": "Lacombe County, Alberta",
"City": "Lacombe County",
"Region": "Alberta"
},
"extent": {
"xmin": -113.613535729,
"ymin": 52.472597831,
"xmax": -113.593535729,
"ymax": 52.492597831
}
}The solution for this case is to pass the category parameter in the request. By including category= in the request, all places that are not ski resorts are bypassed by the search, and only ski resorts whose names begin with June are returned.
Example
Search for "June" with category=
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=June&category=Ski Resort&outFields=PlaceName,Type,Place_Addr,City,Region&maxLocations=5&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "June Mountain Ski Area",
"location": {
"x": -119.1217968,
"y": 37.8256044
},
"score": 84.96,
"attributes": {
"Type": "Ski Resort",
"PlaceName": "June Mountain Ski Area",
"Place_Addr": "3819 State Highway 158, June Lake, California, 93529",
"City": "June Lake",
"Region": "California"
},
"extent": {
"xmin": -119.1267968,
"ymin": 37.8206044,
"xmax": -119.1167968,
"ymax": 37.8306044
}
}
]
}See Category filtering for details.
Using the langCode parameter
In some countries, multiple languages are spoken, and an address may be available in different languages. You may want to search for an address in one language but return it in another. The lang parameter is useful in this case. For instance, you may have an address in Israel that is in the Hebrew language and you want to geocode it and return the address in English.
Example
Example: Search for Hebrew address "הרימון 4, רמת גן" and return it in English
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=הרימון 4, רמת גן&langCode=EN&outFields=LangCode,Addr_type&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=הרימון 4&city=רמת גן&langCode=EN&outFields=LangCode,Addr_type&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "HaRimmon Street 4, Ramat Gan",
"location": {
"x": 34.808695257572,
"y": 32.08775764427
},
"score": 99.41,
"attributes": {
"Addr_type": "StreetAddress",
"LangCode": "ENG"
},
"extent": {
"xmin": 34.807695257572,
"ymin": 32.08675764427,
"xmax": 34.809695257572,
"ymax": 32.08875764427
}
}
]
}Using the preferredLabelValues parameter
The preferred parameter allows limited customization of output values in find responses. Refer to the parameter overview for details about its functionality; this section includes examples showing how it can be used.
The preferred 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. 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. For instance, one of the postal codes used in the city of Edgewood, Washington, is 98371. The primary name assigned to postal code 98371 is Puyallup, a city adjacent to the city of Edgewood. When addresses with postal code 98371 are geocoded by the ArcGIS Geocoding service, the output labels and fields include Puyallup as the city name by default.
The following examples illustrate how to use the preferred parameter to modify the output city name for address 2420 Meridian Ave E, Edgewood, W in Edgewood, Washington. Without the parameter, Puyallup is included in geocoding results as the city name:
Example
Search for address "2420 Meridian Ave E, Edgewood, WA 98371" without preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=2420 Meridian Ave E, Edgewood, WA 98371&preferredLabelValues=&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=2420 Meridian Ave E&city=Edgewood®ion=WA&postal=98371&preferredLabelValues=&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "2420 Meridian Ave E, Puyallup, Washington, 98371",
"location": {
"x": -122.29413591243,
"y": 47.234864146322
},
"score": 100,
"attributes": {
"Match_addr": "2420 Meridian Ave E, Puyallup, Washington, 98371",
"City": "Puyallup"
},
"extent": {
"xmin": -122.29513591243,
"ymin": 47.233864146322,
"xmax": -122.29313591243,
"ymax": 47.235864146322
}
}
]
}The preferred parameter can be used to return a more suitable city name for this address in geocoding results. Pass preferred in the find request to return Edgewood as the city name in the output.
Example
Search for address "2420 Meridian Ave E, Edgewood, WA 98371" with preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=2420 Meridian Ave E, Edgewood, WA 98371&preferredLabelValues=localCity&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=2420 Meridian Ave E&city=Edgewood®ion=WA&postal=98371&preferredLabelValues=localCity&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "2420 Meridian Ave E, Edgewood, Washington, 98371",
"location": {
"x": -122.29413591243,
"y": 47.234864146322
},
"score": 100,
"attributes": {
"Match_addr": "2420 Meridian Ave E, Edgewood, Washington, 98371",
"City": "Edgewood"
},
"extent": {
"xmin": -122.29513591243,
"ymin": 47.233864146322,
"xmax": -122.29313591243,
"ymax": 47.235864146322
}
}
]
}In some cases, there are multiple postal or local city names associated with an address, and you may want to use the city name that was searched for in geocoding results instead of the primary postal or local city name. The matched option of the preferred parameter supports this. The city of Merriam, Kansas, is part of the Mission postal area, for which there are several alternate postal city names; one of these is Shawnee Mission. If you search for an address in this area without using the preferred parameter, Mission is returned as the city name by default, as illustrated in the following example.
Example
Search for address "9001 W 62nd St, Shawnee Mission, KS 66202" without preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=9001 W 62nd St, Shawnee Mission, KS 66202&preferredLabelValues=&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=9001 W 62nd St&city=Shawnee Mission®ion=KS&postal=66202&preferredLabelValues=&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "9001 W 62nd St, Mission, Kansas, 66202",
"location": {
"x": -94.689890954033,
"y": 39.016897077214
},
"score": 99.9,
"attributes": {
"Match_addr": "9001 W 62nd St, Mission, Kansas, 66202",
"City": "Mission"
},
"extent": {
"xmin": -94.690890954033,
"ymin": 39.015897077214,
"xmax": -94.688890954033,
"ymax": 39.017897077214
}
}
]
}If preferred is passed in the find request for the same address, Shawnee Mission is returned as the city name instead:
Example
Search for address "9001 W 62nd St, Shawnee Mission, KS 66202" with preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=9001 W 62nd St, Shawnee Mission, KS 66202&preferredLabelValues=matchedCity&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=9001 W 62nd St&city=Shawnee Mission®ion=KS&postal=66202&preferredLabelValues=matchedCity&outFields=Match_addr,City&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "9001 W 62nd St, Shawnee Mission, Kansas, 66202",
"location": {
"x": -94.689890954033,
"y": 39.016897077214
},
"score": 99.9,
"attributes": {
"Match_addr": "9001 W 62nd St, Shawnee Mission, Kansas, 66202",
"City": "Shawnee Mission"
},
"extent": {
"xmin": -94.690890954033,
"ymin": 39.015897077214,
"xmax": -94.688890954033,
"ymax": 39.017897077214
}
}
]
}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. The street in the following example has two names—I is designated as the primary name, and Highway 62 W is an alternate name. If you search for an address on this street by its alternate name Highway 62 W , without using the preferred parameter, Highway 62 W is included in the output fields of the geocoding response:
Example
Example: Search for address "71 Highway 62 W, Mount Vernon, Indiana, 47620" without preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=71 Highway 62 W, Mount Vernon, Indiana, 47620&preferredLabelValues=&outFields=Match_addr,StAddr&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=71 Highway 62 W&city=Mount Vernon®ion=Indiana&postal=47620&preferredLabelValues=&outFields=Match_addr,StAddr&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "71 Highway 62 W, Mount Vernon, Indiana, 47620",
"location": {
"x": -87.895667387148,
"y": 37.932216595452
},
"score": 98.9,
"attributes": {
"Match_addr": "71 Highway 62 W, Mount Vernon, Indiana, 47620",
"StAddr": "71 Highway 62 W"
},
"extent": {
"xmin": -87.896667387148,
"ymin": 37.931216595452,
"xmax": -87.894667387148,
"ymax": 37.933216595452
}
}
]
}However, your use case may require that the standardized street names recognized as primary by the postal authority be returned by the geocoding application. If so, you can pass preferred in the find request. For the previous example, 70 Highway 62 W, Mount Vernon, Indiana, 47620 , doing so causes W 4th St to be returned as the street name:
Example
Search for address "71 Highway 62 W, Mount Vernon, Indiana, 47620" with preferred
Single-field request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?singleLine=71 Highway 62 W, Mount Vernon, Indiana, 47620&preferredLabelValues=primaryStreet&outFields=Match_addr,StAddr&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>Multifield request URL
https://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer/findAddressCandidates?address=71 Highway 62 W&city=Mount Vernon®ion=Indiana&postal=47620&preferredLabelValues=primaryStreet&outFields=Match_addr,StAddr&maxLocations=1&forStorage=false&f=pjson&token=<ACCESS_TOKEN>JSON response
{
"spatialReference": {
"wkid": 4326,
"latestWkid": 4326
},
"candidates": [
{
"address": "71 W 4th St, Mount Vernon, Indiana, 47620",
"location": {
"x": -87.895667387148,
"y": 37.932216595452
},
"score": 98.9,
"attributes": {
"Match_addr": "71 W 4th St, Mount Vernon, Indiana, 47620",
"StAddr": "71 W 4th St"
},
"extent": {
"xmin": -87.896667387148,
"ymin": 37.931216595452,
"xmax": -87.894667387148,
"ymax": 37.933216595452
}
}
]
}