Locators allow you to find addresses and places that you can visualize on a map, insert as stops for a route, and load as input for spatial analysis. ArcGIS Online locators include geosearch and geocoding as follows:
- Geosearch (also known as location search)—Locate an address or point of interest and have the map zoom to that location. The result can be displayed on the map, but the result is not stored in any way for later use. Geosearch is available to anyone who accesses Map Viewer, Map Viewer Classic, or a public app that includes a location search on a map. It does not require an organizational account or consume credits (but you are limited to 1 million geosearches per month).
- Geocoding—Convert an address or place to an x,y coordinate and append the result to an existing record in a database. Mapping is not always involved, but placing the results on a map may be part of a workflow. Batch geocoding and reverse geocoding fall into this category. An organizational account with the premium content geocoding privilege is required to access ArcGIS World Geocoding Service, and any views of it, for batch geocoding.
Note:
Some locator view properties are not supported for reverse geocoding.
By default, ArcGIS Online uses ArcGIS World Geocoding Service to find addresses, cities, landmarks, business names, and postal codes in more than 100 countries around the world. Additionally, ArcGIS World Geocoding Service is used to find the location of x,y coordinates using longitude and latitude, as well as coordinate reference systems such as Military Grid Reference System (MGRS) and United States National Grid (USNG).
If your organization wants to optimize search results for addresses and places of interest, members with privileges to create content can create a new view of ArcGIS World Geocoding Service to search only for specific types of locations within an area of interest. For example, you can create a locator view to limit search results to a particular country or area or to only return results that match a specific category such as street addresses or airports. Once you create a locator view, members of the default administrator role can configure the organization so it uses your locator view when members perform geosearches.
Note:
Using ArcGIS World Geocoding Service or views of this locator for batch geocoding (including publishing CSV or Microsoft Excel files as hosted feature layers) consumes credits. Using locators for geosearch does not consume credits.
An organizational account with the premium content geocoding privilege is required to use locator views for batch geocoding.
In addition, if your organization needs to geocode addresses or places based on its own data, administrators can configure your organization to use its own locators running on an ArcGIS Server site for geosearch, geocoding, or both. For example, an oil organization can add locators to search its oil wells, or a city can add a locator to find its fire hydrants.
If you add additional locators or locator views, members see an arrow in the geosearch box and can choose which locator or view to use.
Location types and categories
This section describes the location types, categories, and subcategories available when you configure the locator view.
Addresses, Postal Codes and Populated Places
When you choose Addresses, Postal Codes and Populated Places as the types of locations you want to find, you can further refine the locator view's search results by selecting the categories and subcategories you want to search. The following categories for Addresses, Postal Codes and Populated Places are available:
- Address—Selecting this category automatically includes all of the address subcategories listed in the table below. This category limits search results to places that can be categorized as addresses while filtering out results for places of interest, postal codes, countries, or states. For more precise search results, choose any combination of address subcategories that meet your search requirements.
- Postal—Selecting this category limits search results to any type of postal code match, including five-digit and longer postal code formats. To limit search results to matches that are at least this precise, select both the Postal category and the top-level Address category.
- Populated Place—Selecting this category automatically includes all of the populated place subcategories listed in the table below. This category limits search results to administrative divisions (or boundaries), such as cities, provinces, or countries, while filtering out results for addresses, places of interest, and postal codes. For more precise search results, choose any combination of populated place subcategories that meet your search requirements.
| Category | Subcategory | Description |
|---|---|---|
Address | Point Address | A point address is a street address based on points that represent house and building locations. Point addresses represent the rooftop, or actual, location of the address. Typically, this is the most spatially accurate match level. Reference data contains address points with associated house numbers and street names, along with administrative divisions and optional postal code information—for example, 380 New York St, Redlands, CA, 92373. A locator view configured with this subcategory limits results to these highly precise address points, which allows you to avoid matching to any less-precise address points if you require high precision in matching. |
Street Address | A street address is different from a point address in that the house number in a street address is interpolated from a range of numbers. Reference data contains street centerlines with house number ranges, along with administrative divisions and optional postal code information—for example, 647 Haight St, San Francisco, CA, 94117. A locator view configured with this subcategory limits results to an interpolated result. If you want to limit results to matches that are at least this precise, you should select both this subcategory and the Point Address category. | |
Intersection | An intersection is a street address consisting of a street intersection along with city and optional state and postal code information—for example, Redlands Blvd & New York St, Redlands, CA, 92373. A locator view configured with this subcategory limits results to intersections instead of complete addresses that exist on only one street. | |
Street Name | A street name is similar to a street address but without the house number. It contains street centerlines with associated street names (no numbered address ranges), along with administrative divisions and optional postal code information—for example, W Olive Ave, Redlands, CA, 92373. A locator view configured with this subcategory limits results to street names only. If you want to limit results to matches that are at least this precise, you should select this subcategory as well as the Point Address and Street Address subcategories. | |
Subaddress | A subaddress is a subset of a point address that represents a house or building subset location such as an apartment unit, floor, or individual building within a building complex—for example, 3836 Emerald Ave, Suite C, La Verne, CA, 91750. A locator view configured with this subcategory limits results to subaddress points that include a house number, street name, and subaddress elements, along with administrative divisions and optional postal code information, while leaving out other types of address matches. | |
Postal | No subcategories | A locator view configured with the Postal category returns any type of postal code match, including five-digit (for example, 92373) and other postal code formats. To limit results to matches that are at least this precise, select Postal and the top-level Address category. |
Populated Place | Neighborhood | A neighborhood is a subsection of a city, smaller than a district and larger than a sector. |
City | A locator configured with this subcategory limits results to cities only—for example, the city of Venice in Italy. | |
Subregion | A subregion is a subset of a state or province, such as a county in the United States—for example, Adams County in the state of Wisconsin. | |
Region | A region is a subsection of a country, typically a state or province—for example, the province of Ontario in Canada. | |
Country | A country is the highest administrative division, also known as a nation—for example, Japan. | |
Sector | A sector is an administrative division larger than a block and smaller than a neighborhood, representing a subdivision of a neighborhood or district, or a collection of blocks. | |
Block | A block is the smallest administrative area for a country, representing a subdivision of a sector or neighborhood, or a named city block. | |
District | A district is an administrative division smaller than a city and larger than a neighborhood—for example, a municipal district. | |
Metro Area | A metropolitan (metro) area is an urban conglomeration consisting of a large city and the smaller cities surrounding it—for example, Greater Tokyo. | |
Territory | A territory is a large administrative division, smaller than a country and larger than a state or province—for example, the Yukon territory in Canada. | |
Zone | A zone is a category representing an unofficial administrative area that does not belong to a country, such as a disputed area or a grouping of other administrative zones—for example, Central America. |
Coordinates
When you choose Coordinates as the types of locations you want to find, you can further refine the locator view's search results by selecting the categories you want to search. These are described in the table below.
| Category | Description |
|---|---|
Longitude, Latitude | This category represents geographic (x,y) coordinates. X refers to longitude (east-west coordinates), and y refers to latitude (north-south coordinates). Coordinates are entered and returned as x,y. |
Latitude, Longitude | This category represents geographic (x,y) coordinates. X refers to longitude (east-west coordinates) and y refers to latitude (north-south coordinates). Coordinates are entered and returned as y,x. |
MGRS | This category represents Military Grid Reference System (MGRS) coordinates. |
USNG | This category represents the United States National Grid (USNG) coordinate system. |
Places of Interest
When you choose Places of Interest as the types of locations you want to find, you can further refine the locator view's search results by selecting the categories you want to search. These are described in the table below.
| Category | Description |
|---|---|
Education | This category represents all types of educational institutions, including universities, primary schools, and vocational schools. |
Food | This category represents restaurants of all types. |
Shops and Service | This category represents all types of commercial or retail businesses. |
Airport | This category represents airports, designated either by name or by airport code. |
Requirements for configuring your own locators
ArcGIS Online supports locators running on ArcGIS Server 10.0 and later as locators for geosearch. When used for geosearch, the locators can be internal or external. Internal locators only work for geosearch when Map Viewer Classic or other ArcGIS Online clients have access to those internal locators. For example, if your organization shares apps with the public, only users who have access to your internal locators will be able to find places with those apps.
ArcGIS Online also supports locators running on ArcGIS Server 10.1 and later as geocoders for batch geocoding. Unlike geosearch, external locators that are hosted outside your firewall are required for batch geocoding. This is because ArcGIS Online needs to access the geocodeAddresses operation on your locator to perform batch geocoding. If your external locator is secure, you must first create a secure service item in ArcGIS Online that stores the credentials required to access your locator. You can then configure the service URL provided by the secure service item as a locator.
When you configure your own locator for batch geocoding, you should provision sufficient compute resources for your locator. ArcGIS Online submits many concurrent requests when performing batch geocoding to improve performance, so your own locators should have sufficient compute resources to handle concurrent requests without severely affecting processing times for the requests.
ArcGIS Online supports single-field locators from ArcGIS Server 10.0 and later. Locators from ArcGIS Server 10.0 and internal locators can be used for geosearch but not to batch geocode. External locators from ArcGIS Server 10.1 or later are required to perform batch geocoding. Internal locators only work for geosearch when Map Viewer, Map Viewer Classic, or other ArcGIS Online clients have access to those internal locators. For example, if your organization shares apps with the public, only users who have access to your internal locators will be able to find places with those apps. ArcGIS Online secure service items are not currently supported in ArcGIS Desktop. To batch geocode, your locator needs to be hosted outside your firewall so ArcGIS Online can access the geocodeAddresses operation on your locator to perform batch geocoding.
Enrich layer with address information
When you publish a hosted feature layer from a comma-separated values file, you have the option to include information from the geocoding process as part of your hosted feature layer. This information is generated by the locator and is stored in fields in the hosted feature layer.
By default, only the location information (the x,y coordinates) is included in the hosted feature layer. There are two options to include additional information in the hosted feature layer:
- Append four fields that show how well addresses matched—Includes status, score, match_addr, and addr_type fields and values. These fields and values are described in the following table.
- Append 50 fields for full location information—Includes all fields listed in the following table.
Be aware that these additional fields and values will increase the size of the hosted feature layer. How much the layer size increases depends on the number of records in the input file and which option you choose. The following table describes the fields you can append to a hosted feature layer published from a .csv file:
| Field | Description | Supported request types |
|---|---|---|
spatialReference | The spatial reference of the output match location coordinates as specified by the wkid and latestWkid properties. The outSR input parameter determines the spatial reference. | findAddressCandidates geocodeAddresses reverseGeocode |
address | The complete matching address returned for findAddressCandidates and geocodeAddresses geocode requests. Example: 380 New York St, Redlands, California, 92373 | findAddressCandidates geocodeAddresses |
address (reverseGeocode only) | The full street address of a location, including house number and street name. Example: 380 New York St Note:This is different than the address field that is returned in responses for findAddressCandidates and geocodeAddresses requests. It is only returned for reverseGeocode. It is analogous to the StAddr output field for findAddressCandidates and geocodeAddresses. | reverseGeocode |
location | The point coordinates of the output match location as specified by the x and y properties. The spatial reference of the x and y coordinates is defined by the spatialReference output field. Refer to the description of the locationType parameter for more information about how the location output field relates to the x and y output attributes. For reverseGeocode specifically, refer to the description of the returnInputLocation parameter to learn how it can be used to modify the output location coordinates. | findAddressCandidates geocodeAddresses reverseGeocode |
ResultID | This is only returned for geocodeAddresses requests. Each record in a batch geocode response includes a ResultID value, which equals the OBJECTID value of the corresponding input address record. It can be used to join the output fields in the response to the attributes in the original address table. | geocodeAddresses |
Loc_name | The name of the locator used to return a particular match result. Note:The Loc_name field is used internally by ArcGIS software and is not intended for use by client applications. | findAddressCandidates geocodeAddresses |
Status | Indicates whether a geocode request results in a match, a tie, or is unmatched. The possible values are the following:
| findAddressCandidates geocodeAddresses |
Score | A number from 1–100 indicating the degree to which the input tokens in a geocoding request match the address components in a candidate record. A score of 100 represents a perfect match, while lower scores represent decreasing match accuracy. | findAddressCandidates geocodeAddresses |
Match_addr | The complete address returned for the geocode request. The format is based on address standards for the country in which the address is located. | findAddressCandidates geocodeAddresses reverseGeocode |
LongLabel | A longer version of the Match_addr value containing more administrative information. | findAddressCandidates geocodeAddresses reverseGeocode |
ShortLabel | A shortened version of the Match_addr value. | findAddressCandidates geocodeAddresses reverseGeocode |
Addr_type | The match level for a geocode request. Supported match levels vary in different countries. The possible values are the following:
| findAddressCandidates geocodeAddresses reverseGeocode |
Type | The feature type for results returned by a search. The Type field only includes a value for candidates with Addr_type = POI or Locality. As an example, for Starbucks, Type=Coffee Shop. | findAddressCandidates geocodeAddresses reverseGeocode |
PlaceName | The formal name of a geocode match candidate. Example: Paris or Starbucks. | findAddressCandidates geocodeAddresses reverseGeocode |
Place_addr | The full street address of a place, including street, city, and region. Example: 275 Columbus Ave, New York, New York. | findAddressCandidates geocodeAddresses |
Phone | The primary phone number of a place of interest (POI). Example: Knott's Berry Farm, Phone=(714)220-5200. For other searches, such as address, intersection, and postal code, the field is empty. | findAddressCandidates geocodeAddresses |
URL | The URL of the primary website for a place of interest (POI). Example: the University of Georgia, URL =http://www.uga.edu/. For other searches, such as address, intersection, and postal code, the field is empty. | findAddressCandidates geocodeAddresses |
Rank | A floating-point number value indicating the priority of a result relative to other results with the same name. For example, there are cities in France and Texas named Paris. Paris, France, has a greater population than Paris, Texas, so it has a higher rank. The Rank field is used to sort results for ambiguous queries such as Lincoln, when no additional information (state) is available. Rank values are based on population or feature type. | findAddressCandidates geocodeAddresses |
AddBldg | The name of a building. Example: Empire State Building. | findAddressCandidates geocodeAddresses |
AddNum | The alphanumeric value that represents the portion of an address typically known as a house number or building number. Example: in the address 380 New York Street, AddNum = 380. This value is returned for PointAddress and StreetAddress matches only. | findAddressCandidates geocodeAddresses reverseGeocode |
AddNumFrom | A value representing the beginning number of a street address range. It is relative to direction of feature digitization and is not always the smallest number in the range. This value is provided for StreetAddress results. | findAddressCandidates geocodeAddresses |
AddNumTo | A value representing the ending number of a street address range. It is relative to direction of feature digitization and is not always the largest number in the range. This value is provided for StreetAddress results. | findAddressCandidates geocodeAddresses |
AddRange | The full house number range for the street segment that an address lies on, in the format AddNumFrom-AddNumTo. For example, the AddRange value for street address 123 Main St may be 101-199. | findAddressCandidates geocodeAddresses |
Side | The side of the street where an address resides relative to the direction of feature digitization. This value is not relative to the direction of travel along the street. Possible values are R(right) and L (left). Note:Side is a legacy field that is kept in place only to support applications that expect it to be present in the REST response. The field is empty for most addresses returned by the geocoding service. It should not be used for analysis purposes. | findAddressCandidates geocodeAddresses |
StPreDir | An address element defining the direction of a street and occurs before the primary street name. Example: North in North Main Street. | findAddressCandidates geocodeAddresses |
StPreType | An address element defining the leading type of a street. Example: the Spanish term Avenida in Avenida Central or the French term Rue in Rue Lapin. | findAddressCandidates geocodeAddresses |
StName | An address element defining the primary name of a street. Example: Main in North Main Street. | findAddressCandidates geocodeAddresses |
StType | An address element defining the trailing type of a street. Example: Street in Main Street. | findAddressCandidates geocodeAddresses |
StDir | An address element defining the direction of a street, which occurs after the primary street name. Example: North in Main Street North. | findAddressCandidates geocodeAddresses |
BldgName | The name or number of a building subunit. Example: A in building A. | findAddressCandidates geocodeAddresses |
BldgType | The classification of a building subunit. Examples are building, hangar, and tower. | findAddressCandidates geocodeAddresses |
LevelType | The classification of a floor subunit. Examples are floor, level, department, and wing. | findAddressCandidates geocodeAddresses |
LevelName | The name or number of a floor subunit. Example: 3 in level 3. | findAddressCandidates geocodeAddresses |
UnitType | The classification of a unit subunit. Examples are unit, apartment, flat, office, and suite. | findAddressCandidates geocodeAddresses |
UnitName | The name or number of a unit subunit. Example: 2B in apartment 2B. | findAddressCandidates geocodeAddresses |
SubAddr | The full subunit value for a candidate with Addr_type=Subaddress that includes <subunit type> + <subunit name>. For example, if the subaddress candidate is an apartment unit, SubAddr = UnitType + UnitName. Example: Apt 4B | findAddressCandidates geocodeAddresses |
StAddr | The street address of a place, without city and region. Example: 275 Columbus Ave. | findAddressCandidates geocodeAddresses |
Block | The name of the block-level administrative division for a candidate. The Block value is the smallest administrative area for a country. It can be described as a subdivision of sector or neighborhood or a named city block. It is not commonly used. | findAddressCandidates geocodeAddresses reverseGeocode |
Sector | The name of the sector-level administrative division for a candidate. The Sector value is a subdivision of a neighborhood or district, or represents a collection of blocks. It is not commonly used. | findAddressCandidates geocodeAddresses reverseGeocode |
Nbrhd | The name of the neighborhood-level administrative division for a candidate. The Nbhrhd value is a subsection of a city or district. | findAddressCandidates geocodeAddresses |
Neighborhood | The name of the neighborhood-level administrative division for a candidate. The Neighborhood value is a subsection of a city or district. Note:This is analogous to the Nbhrhd output field for findAddressCandidates and geocodeAddresses requests. | reverseGeocode |
District | The name of the district-level administrative division for a candidate. Such as a subdivision of a city. | findAddressCandidates geocodeAddresses reverseGeocode |
City | The name of the city-level administrative division for a candidate. The City value is a subdivision of a subregion or region. | findAddressCandidates geocodeAddresses reverseGeocode |
MetroArea | The name of the metropolitan area-level administrative division for a candidate. It is an urban area consisting of a large city and the smaller cities surrounding it. The value can potentially intersect multiple subregions or regions. An example is Kolkata Metropolitan Area in India. | findAddressCandidates geocodeAddresses reverseGeocode |
Subregion | The name of the subregion-level administrative division for a candidate. The Subregion value is a subdivision of a region. | findAddressCandidates geocodeAddresses reverseGeocode |
Region | The name of the region-level administrative division for a candidate. It is a subdivision of a country or territory. It is typically the largest administrative area for a country if the Territory administrative division is not used. | findAddressCandidates geocodeAddresses reverseGeocode |
RegionAbbr | The abbreviated region name. The RegionAbbr value for California is CA. | findAddressCandidates geocodeAddresses reverseGeocode |
Territory | The name of the territory-level administrative division for a candidate. It is a subdivision of country. It is not commonly used. The Sudeste macroregion of Brazil, which encompasses the states of Espírito Santo, Minas Gerais, Rio de Janeiro and São Paulo, is an example. | findAddressCandidates geocodeAddresses reverseGeocode |
Postal | An alphanumeric address element defining the primary postal code. Example: V7M 2B4 for a Canadian postal code and 92374 for a United States postal code. | findAddressCandidates geocodeAddresses reverseGeocode |
PostalExt | An alphanumeric address element defining the postal code extension. Example: 8100 in USA postal code 92373-8110. | findAddressCandidates geocodeAddresses reverseGeocode |
Country | A 3-character code for a country. Example: Canada is CAN. A list of supported countries and codes is available in Geocode data coverage. This field is returned by the findAddressCandidates and geocodeAddresses operations. | findAddressCandidates geocodeAddresses |
CountryCode | A 3-character code for a country. Example: Canada is CAN. A list of supported countries and codes is available in Geocode data coverage. Note:This is analogous to the Country output field for findAddressCandidates and geocodeAddresses requests. | reverseGeocode |
CntryName | The full country name for an address candidate. Example: 日本 (Japan). The name may be in the same language as the input address or in the language specified by the langCode parameter for the request. If the full country name is not available in the specified language, the primary language of the country that the address candidate is in is used. Information about supported languages by country is available in Geocode data coverage. This field is returned by the findAddressCandidates, geocodeAddresses, and reverseGeocode operations. | findAddressCandidates geocodeAddresses reverseGeocode |
LangCode | A 3-character language code representing the language of the address. Example: ENG is English. | findAddressCandidates geocodeAddresses |
Distance | The physical distance in meters from a candidate to a specified location. The Distance output value is calculated for each candidate when the Location input parameter is passed in a request using the findAddressCandidates operation. If the Location parameter is not passed in a request, the value of Distance is zero. | findAddressCandidates |
X | The primary x-coordinate of an address returned by the ArcGIS World Geocoding Service in spatial reference WGS84 (WKID 4326). | findAddressCandidates geocodeAddresses reverseGeocode |
Y | The primary y-coordinate of an address returned by the ArcGIS World Geocoding Service in spatial reference WGS84 (WKID 4326). | findAddressCandidates geocodeAddresses reverseGeocode |
InputX | The x-coordinate that was submitted in a reverseGeocode request for the location parameter | reverseGeocode |
InputY | The y-coordinate that was submitted in a reverseGeocode request for the location parameter | reverseGeocode |
DisplayX | The display x-coordinate of an address returned by the ArcGIS World Geocoding Service in spatial reference WGS84 (WKID 4326). For most types of matches, the X and DisplayX values are the same. For matches of Addr_type, PointAddress, and Subaddress specifically, the values may be different. In general, for PointAddress and Subaddress matches, DisplayX represents the x-coordinate value of the building rooftop or parcel centroid for the address, and the X value represents the x-coordinate of the street-side location for the address. There are exceptions however. Some address data sources used by the ArcGIS World Geocoding Service only provide the rooftop location of PointAddress and Subaddress features. However, for some PointAddress and Subaddress features, only the street-side location is available. For these cases, the X and DisplayX values are equivalent. | findAddressCandidates geocodeAddresses |
DisplayY | The display y-coordinate of an address returned by the ArcGIS World Geocoding Service in spatial reference WGS84 (WKID 4326). For most types of matches, the Y and DisplayY values are the same. For matches of Addr_type, PointAddress, and Subaddress specifically, the values may be different. In general, for PointAddress and Subaddress matches, DisplayY represents the y-coordinate value of the building rooftop or parcel centroid for the address, and the Y value represents the y-coordinate of the street-side location for the address. There are exceptions however. Some address data sources used by the ArcGIS World Geocoding Service only provide the rooftop location of PointAddress and Subaddress features. However, for some PointAddress and Subaddress features, only the street-side location is available. For these cases, the Y and DisplayY values are equivalent. | findAddressCandidates geocodeAddresses |
Xmin | The minimum x-coordinate for the display extent of a feature returned by the ArcGIS World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference. | findAddressCandidates geocodeAddresses |
Xmax | The maximum x-coordinate for the display extent of a feature returned by the ArcGIS World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference. | findAddressCandidates geocodeAddresses |
Ymin | The minimum y-coordinate for the display extent of a feature returned by the ArcGIS World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference. | findAddressCandidates geocodeAddresses |
Ymax | The maximum y-coordinate for the display extent of a feature returned by the ArcGIS World Geocoding Service. The Xmin, Xmax, Ymin, and Ymax values can be combined to set the map extent for displaying a geocode result. The extent coordinates use the WGS84 spatial reference. | findAddressCandidates geocodeAddresses |
ExInfo | A collection of strings from the input that could not be matched to any part of an address and were used to score or penalize the result. | findAddressCandidates geocodeAddresses |
extent | The minimum bounding rectangle of the output match feature as specified by the Xmin, Ymin, Xmax, and Ymax field values. The spatial reference of the x- and y-coordinates is defined by the spatialReference output field. This is always returned by default for findAddressCandidates geocode requests only. | findAddressCandidates |