Part 2 - Locating Addresses

Geocode Address

The geocode() function supports searching for places and addresses either in a single field format or in a multi-field format with the address components separated into multiple parameters.

The code below imports the geocode function and displays its signature and parameters, along with a brief description:

Input
from arcgis.geocoding import geocode
Input
help(geocode)
Help on function geocode in module arcgis.geocoding._functions:

geocode(address, search_extent=None, location=None, distance=None, out_sr=None, category=None, out_fields='*', max_locations=20, magic_key=None, for_storage=False, geocoder=None, as_featureset=False, match_out_of_range=True, location_type='street', lang_code=None, source_country=None)

Single-line address

geocode() can be called with one required parameter address or can be used with optional parameters to fine-tune the search results such as search_extent, as seen in this example.

  • The address parameter specifies the location to be geocoded. This can be a string containing the single line address, i.e street address, place name, postal code, or POI.
Input
from arcgis.gis import GIS
gis = GIS(profile = "your_enterprise_profile") # log in with your own enterprise or AGOL profile configuration

As seen in Part 1, geocode performed upon a single line address returns matched geocoded results. The more details provided onto the address string, the more refined result set becomes.

Input
single_line_address = "380 New York Street, Redlands, CA 92373"
Input
# geocode the single line address
esrihq = geocode(single_line_address)
len(esrihq)
Output
1

If we loosen up on the single-line address definition, e.g. remove the city and state name, then the length of the returned result set increases to 20.

Input
single_line_address = "380 New York Street"
Input
# geocode the single line address
esrihq = geocode(single_line_address)
len(esrihq)
Output
20

Example of World Series POI

Another example of such is to define the single line address of search to be Disneyland, USA, as compared to Disneyland. The former returns matched results in USA only while the latter is returning all in the world.

Input
disney = geocode("Disneyland, USA")
len(disney)
Output
3
Input
for i in range(3):
    print(disney[i]['attributes']['LongLabel'])
    print(" - ",disney[i]['attributes']['Score'], 
          " - ", disney[i]['attributes']['Addr_type'], 
          " - ", disney[i]['attributes']['Type'])
Disneyland, 1313 S Disneyland Dr, Anaheim, CA, 92802, USA
 -  100  -  POI  -  Amusement Park
Disneyland, Anaheim, CA, USA
 -  100  -  Locality  -  Neighborhood
Disneyland, 1313 S Harbor Blvd, Anaheim, CA, 92802, USA
 -  100  -  POI  -  Business Facility
Input
disney = geocode("Disneyland")
len(disney)
Output
20
Input
for i in range(20):
    if disney[i]['attributes']['Type']== "Amusement Park":
        print(disney[i]['attributes']['LongLabel'])
        print(" - ",disney[i]['attributes']['Score'], 
              " - ", disney[i]['attributes']['Addr_type'])
Disneyland, 1313 S Disneyland Dr, Anaheim, CA, 92802, USA
 -  100  -  POI
Disney Land, 7th Street, Gandhipuram, Coimbatore, Tamil Nadu, 641012, IND
 -  100  -  POI
Disney Land, Kalawad Road, Mota Mava, Rajkot, Gujarat, 360005, IND
 -  100  -  POI
Disneyland, Boulevard du Parc, 77700, Coupvray, Seine-et-Marne, Ile-de-France, FRA
 -  100  -  POI

Multi-field address

Alternatively, the address can be specified in a multi-field format using a dict containing the various address fields accepted by the corresponding geocoding service.

In order to provide a way to find addresses in many different countries, which may use different addressing formats, the geocode() method uses standardized field names for submitting address components. In understanding what specific fields are needed to enter for your address, you can check out the `addressField` introduction for more information.

The Geocoder's address field property specifies the various address fields accepted by it when geocoding addresses. 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.

For example, if the address field of a geocoding service resource includes fields with the following names: Address, City, Region and Postal, then the address argument is of the form below.

Input
multi_field_address = { 
                        "Address" : "380 N Y St",
                        "City" : "Redlands",
                        "Region" : "CA",
                        "Postal" : 92373
                      }
Input
# geocode the multi_field_address
esrihq1 = geocode(multi_field_address)
len(esrihq1)
Output
2

The returned result set contains two dict objects, and we can see from below that each dict object contains 'address', 'location', 'score', 'attributes', and 'extent' keys. The x and y coordinates can be found in both location and attributes properties.

Input
esrihq1[0].keys()
Output
dict_keys(['address', 'location', 'score', 'attributes', 'extent'])
Input
esrihq1[0]['location'], esrihq1[0]['extent']
Output
({'x': -117.19568252432872, 'y': 34.05723700023128},
 {'xmin': -117.19587199429185,
  'ymin': 34.056237000231285,
  'xmax': -117.19387199429184,
  'ymax': 34.05823700023128})

We can also go one level deeper and check out the address type, X and Y coordinates from its attributes field for more details.

Input
esrihq1[0]['attributes']['Addr_type'], esrihq1[0]['attributes']['X'], esrihq1[0]['attributes']['Y']
Output
('PointAddress', -117.19568252432872, 34.05723700023128)
Input
esrihq1[1]['attributes']['Addr_type'], esrihq1[1]['attributes']['X'], esrihq1[1]['attributes']['Y']
Output
('StreetAddress', -117.18686179838916, 34.05653921319909)

Example of an Indian address

Photo of Taj Mahal (Source: Lonely Planet)

Input
india_mfield_address = { 
                        "Address" : "Taj Mahal",
                        "City": "Agra",
                        'District': 'Taj Ganj',
                        "Region" : 'Uttar Pradesh',
                        "Country": "IND",
                        "Postal" : 282001
                      }
Input
# geocode the multi_field_address
taj_mahal = geocode(india_mfield_address)
len(taj_mahal)
Output
7

Example of a Mexican address

Photo of San Miguel de Allende (Source: National Geography)

Input
mex_mfield_address = { 
                        "Address" : "San Miguel de Allende",
                        "City": 'San Miguel de Allende',
                        "Region" : 'Guanajuato',
                        "Country": "MEX"
                      }
Input
# geocode the multi_field_address
san_miguel = geocode(mex_mfield_address)
len(san_miguel)
Output
20

Example of a Spanish Address

Photo of Sagrada Familia (Source: https://www.culturalplaces.com/)

Input
esp_mfield_address = { 
                        "Address" : "Sagrada Familia",
                        'Nbrhd': 'Sagrada Familia',
                        'District': 'Barcelona',
                        'City': 'Barcelona',
                        'Region': 'Catalunya',
                        "Country": "ESP"
                      }
Input
# geocode the multi_field_address
sag_fam = geocode(esp_mfield_address)
len(sag_fam)
Output
20

Search for street intersections

The following example illustrates how to search for a street intersection. An intersection is where two streets cross each other, and hence 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.

Input
intersection = "redlands blvd and new york st 92373"
Input
multi_field_intersection = { 
    "Address" : "redlands blvd & new york st",
    "City" : "Redlands",
    "Region" : "CA"
    }
Input
map2 = gis.map("Esri, Redlands, CA", 15)
map2
Output
Input
# geocode the intersection address and plot the location of the first geocode result on the map
# either of the two intersection address formats can be used, they give itentical results:

# intersection_result = geocode(intersection)[0]
intersection_result = geocode(multi_field_intersection)[0]
Input
popup = { 
            "title" : "redlands blvd and new york st", 
            "content" : intersection_result['address']
        }
map2.draw(intersection_result['location'], popup)

Understanding the geocoded result

The output fields

The geocode() method returns a list of dict object, and we can look at the first entry of the list (e.g. intersection_result) to determine what the included keys of the dict object are:

Input
intersection_result.keys()
Output
dict_keys(['address', 'location', 'score', 'attributes', 'extent'])
Input
intersection_result['attributes'].keys()
Output
dict_keys(['Loc_name', 'Status', 'Score', 'Match_addr', 'LongLabel', 'ShortLabel', 'Addr_type', 'Type', 'PlaceName', 'Place_addr', 'Phone', 'URL', 'Rank', 'AddBldg', 'AddNum', 'AddNumFrom', 'AddNumTo', 'AddRange', 'Side', 'StPreDir', 'StPreType', 'StName', 'StType', 'StDir', 'StPreDir1', 'StPreType1', 'StName1', 'StType1', 'StDir1', 'StPreDir2', 'StPreType2', 'StName2', 'StType2', 'StDir2', 'BldgType', 'BldgName', 'LevelType', 'LevelName', 'UnitType', 'UnitName', 'SubAddr', 'StAddr', 'Block', 'Sector', 'Nbrhd', 'District', 'City', 'MetroArea', 'Subregion', 'Region', 'RegionAbbr', 'Territory', 'Zone', 'Postal', 'PostalExt', 'Country', 'LangCode', 'Distance', 'X', 'Y', 'DisplayX', 'DisplayY', 'Xmin', 'Xmax', 'Ymin', 'Ymax', 'ExInfo'])

See below for the descriptions for all of the fields that can be returned by geocode():

  • address: Complete matching address returned for findAddressCandidates and geocodeAddresses geocode requests.
  • 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. Always returned by default for findAddressCandidates and geocodeAddresses geocode requests only.
  • 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.
  • attributes: A dict object containing Loc_name, Status, Score, Match_addr, LongLabel, ShortLabel, Addr_type etc. key-value pairs.
  • extent: the display extent of a feature returned by the geocoding service.

Read into a DataFrame

The previous example explained how to get results as a FeatureSet using as_featureset = True parameter, and map the FeatureSet on the Map Widget. Next, we will convert the FeatureSet to a DataFrame and see how the results look.

Input
disney_fset = geocode("Disneyland", as_featureset = True)
disney_fset
Output
<FeatureSet> 20 features
Input
disney_fset.sdf.head()
Output
Loc_name Status Score Match_addr LongLabel ShortLabel Addr_type Type PlaceName Place_addr ... Y DisplayX DisplayY Xmin Xmax Ymin Ymax ExInfo OBJECTID SHAPE
0 World M 100 Disneyland Disneyland, 1313 S Disneyland Dr, Anaheim, CA,... Disneyland POI Amusement Park Disneyland 1313 S Disneyland Dr, Anaheim, California, 92802 ... 33.81533 -117.91895 33.81277 -117.92395 -117.91395 33.80777 33.81777 1 {"x": -117.92369994070933, "y": 33.81532991704...
1 World M 100 Disneyland, Anaheim, California Disneyland, Anaheim, CA, USA Disneyland Locality Neighborhood Disneyland Anaheim, California ... 33.81530 -117.92370 33.81530 -117.93570 -117.91170 33.80330 33.82730 2 {"x": -117.92369999999994, "y": 33.81530000000...
2 World T 100 Disney Land Disney Land, 7th Street, Gandhipuram, Coimbato... Disney Land POI Amusement Park Disney Land 7th Street, Gandhipuram, Coimbatore, Tamil Nad... ... 11.01845 76.96622 11.01845 76.96122 76.97122 11.01345 11.02345 3 {"x": 76.96622000000008, "y": 11.0184500000000...
3 World T 100 Disney Land Disney Land, Guntur Road, Prakasam, Andhra Pra... Disney Land POI Convention Center Disney Land Guntur Road, Prakasam, Andhra Pradesh, 523001 ... 15.51213 80.04665 15.51213 80.04165 80.05165 15.50713 15.51713 4 {"x": 80.04665000000006, "y": 15.5121300000000...
4 World T 100 Disney Land Disney Land, Kalawad Road, Mota Mava, Rajkot, ... Disney Land POI Amusement Park Disney Land Kalawad Road, Mota Mava, Rajkot, Gujarat, 360005 ... 22.27105 70.74842 22.27105 70.74342 70.75342 22.26605 22.27605 5 {"x": 70.74842000000007, "y": 22.2710500000000...

5 rows × 59 columns

Input
disney_fset.sdf.Addr_type
Output
0          POI
1     Locality
2          POI
3          POI
4          POI
5          POI
6          POI
7          POI
8          POI
9          POI
10         POI
11         POI
12         POI
13         POI
14         POI
15         POI
16         POI
17         POI
18         POI
19         POI
Name: Addr_type, dtype: object
Input
disney_fset.sdf.Score
Output
0     100
1     100
2     100
3     100
4     100
5     100
6     100
7     100
8     100
9     100
10    100
11    100
12    100
13    100
14    100
15    100
16    100
17    100
18    100
19    100
Name: Score, dtype: int64

Plot the accuracy of different results as a bar plot

Take the four entries shown in the disney_fset.sdf for example. Since a score of 100 represents a perfect match, while lower scores represent decreasing match accuracy, the first entry is listed with the highest score, representing the best accuracy among all results.

Input
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_axes([0,0,1,1])
addrs = disney_fset.sdf.Match_addr
scores = disney_fset.sdf.Score
ax.bar(addrs,scores)
plt.show()

Advanced Options

Advanced options for the geocode() method to be used for configuring and fine-tuning the search results are listed below:

  • Limit searches to a set of bounding boxes (search_extent param)
  • Defining an origin point location of the search to be used with distance (location & distance parameters)
  • Customizing number of geocode results (max_locations param)
  • Limit searches to exact address range (match_out_of_range param)
  • Limit searches to a particular country (source_country param)
  • Getting results in desired co-ordinate system (out_sr param)
  • Customizing output fields in the geocoded results (out_fields param)
  • Street coordinates vs Rooftop coordinates (location_type param)
  • Geocoding in languages other than English (lang_code)
  • Whether the results of the operation will be persisted (for_storage param)
  • magic_key param. More explanations can be found in part 7.

search_extent parameter

search_extent: An optional string of 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 only within the current map extent.

You can specify the spatial reference of the search_extent coordinates, which is necessary if the map spatial reference is different than that of the geocoding service; otherwise, the spatial reference of the coordinates is assumed to be the same as that of the 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.

as_featureset parameter

as_featureset: An optional boolean. If True, the result set is returned as a FeatureSet object. Otherwise, it is a dictionary.

Example using search_extent & etc.

The example below uses Esri headquarter's bbox as search_extent, and the geocoded results got filtered down to 1 (from the original count of 20).

Input
# geocode the single line address
esrihq_fset = geocode(single_line_address, 
                      search_extent = {'xmin': -117.19587199429185,
                                       'ymin': 34.056237000231285,
                                       'xmax': -117.19387199429184,
                                       'ymax': 34.05823700023128},
                      as_featureset = True)
esrihq_fset
Output
<FeatureSet> 1 features
Input
esrihq_fset.features[0].attributes["Match_addr"]
Output
'380 New York St, Redlands, California, 92373'
Input
map0 = gis.map("Redlands, CA")
map0
Input
# plot the location of the first geocode result on the map
map0.draw(esrihq_fset)

location parameter

location: Optional [x,y] defining an origin point location that is used with the distance parameter to sort geocoding candidates based upon their proximity to the location.

The location parameter defines an origin point location that is used with the distance parameter to sort geocoding candidates based upon their proximity to the location. The distance parameter specifies the radial distance from the location in meters. The priority of candidates within this radius is boosted relative to those outside the radius.

This is useful in mobile applications where a user will want to search for places in the vicinity of their current GPS location; the location and distance parameters can be used in this scenario.

The location parameter can be specified without specifying a distance. If distance is not specified, it defaults to 50000 meters.

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.056 JSON example with a spatial reference: location= { "x": -13046165.572, "y": 4036389.847, "spatialReference": { "wkid": 102100 } }

distance parameter

The distance parameter specifies the radius of an area around a point location that is used to boost the rank of geocoding candidates so that candidates closest to the location are returned first. The distance value is in meters.

If the distance parameter is specified, then the location parameter must be specified as well.

It is important to note that unlike the searchExtent parameter, the location and distance parameters allow searches to extend beyond the specified search radius. They are not used to filter results, but rather to rank resulting candidates based on their distance from a location. You must pass a searchExtent value in addition to location and distance if you want to confine the search results to a specific area.

Example of searching within two miles of the current extent: distance=3218.69

Example using location and distance

Input
# geocode the multi_field_address
esrihq1_fset = geocode(multi_field_address,
                       location={"x":-117.19568252432872, "y":34.05723700023128},
                       distance=0,
                       as_featureset=True)
esrihq1_fset
Output
<FeatureSet> 4 features
Input
map1 = gis.map("Redlands, CA")
map1
Input
map1.draw(esrihq1_fset)

max_locations parameter

The max_locations parameter is the maximum number of locations to be returned by a search, up to the maximum number allowed by the geocoder. If not specified, then all matching candidates up to the maximum are returned.

The World Geocoding Service allows up to 20 candidates to be returned for a single request. Note that up to 50 POI candidates can be returned.

Example:

max_locations=10

category parameter

The category parameter is a place or address type which can be used to filter geocoding results. The parameter supports input of single category values or multiple comma-separated values. The category parameter can be passed in a request with or without a single line address input. More categories can be found in Part 1.

Example of category filtering with a single category:

category="Address"

Example of category filtering with multiple categories:

category="Address,Postal"

Note: The `category` parameter is only functional when used with single line address input. It does not work with multi field addresses; specifically the address, neighborhood, city, region, subregion, countryCode, and postal parameters.

Input
unionsquare = geocode("Union Square, San Francisco, CA")[0]

map3 = gis.map(unionsquare)
map3
Output
Input
# find and plot upto 10 Indian restaurants around Union Square in San Francisco, CA
restaurants = geocode(None, 
                      search_extent = unionsquare['extent'], 
                      category="Indian Food", 
                      max_locations=10)
Input
for restaurant in restaurants:
    popup = { 
        "title" : restaurant['address'], 
        "content" : "Phone: " + restaurant['attributes']['Phone']
    }
    map3.draw(restaurant['location'], popup)

for_storage parameter

This 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_storage parameter with a value of true.

ArcGIS Online service credits are deducted from the organization account for each geocode transaction that includes the for_storage parameter with a value of true. Refer to the ArcGIS Online service credits overview page for more information on how credits are charged.

To learn more about free and paid geocoding operations, see this help topic.

Example:

for_storage=True
Input
starbucks_fset = geocode("Starbucks", unionsquare['extent'], 
                         max_locations=10,
                         as_featureset=True,
                         for_storage=True)
starbucks_fset
Output
<FeatureSet> 10 features

out_sr parameter

The spatial reference of the x/y coordinates returned by the geocode method. This is useful for applications using a map with a spatial reference different than that of the geocoder.

The spatial reference can be specified as either a well-known ID (WKID) or as a JSON spatial reference object. If outSR is not specified, the spatial reference of the output locations is the same as that of the geocoder. The World 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):

out_sr=102100

out_fields parameter

The list of fields to be returned in the response. Descriptions for each of these fields are available in the Output fields section of this document.

The returned address, x/y coordinates of the match location, match score, spatial reference, extent of the output feature, and the addr_type (match level) are returned by default.

Example that returns all output fields:

out_fields=*

Example that returns the specified fields only:

out_fields="AddrNum,StName,City"

Example using out_sr and out_fields

Next, let's look at an example in which we output the result set in a different spatial reference than the default sr, and let's limit the output fields to be only containing Addr_type,AddrNum,StName,City,X,Y columns.

Input
esrihq2 = geocode(multi_field_address,
                  out_sr={
                             "wkid" : 3857,
                             "latestWkid" : 102100
                         },
                  out_fields="Addr_type,AddrNum,StName,City,X,Y")
len(esrihq2)
Output
2
Input
esrihq2[0]['location'], esrihq2[0]['extent']
Output
({'x': -13046163.701778423, 'y': 4036490.1486023655},
 {'xmin': -13046184.79347824,
  'ymin': 4036355.7832219717,
  'xmax': -13045962.154496653,
  'ymax': 4036624.5155679826})

We can compare the output cell shown above to the output without specifying out_sr and out_fields:

({'x': -117.19568252432872, 'y': 34.05723700023128},

 {'xmin': -117.19587199429185,
  'ymin': 34.056237000231285,
  'xmax': -117.19387199429184,
  'ymax': 34.05823700023128})

It is obvious that the x, y coordinates represented in location field, and the bbox as shown in the extents field, have been reprojected. However, if we look at the attributes field of the result, the X and Y responses are still the same as the non-projected ones.

Input
esrihq2[0]['attributes']['Addr_type'], esrihq2[0]['attributes']['X'], esrihq2[0]['attributes']['Y']
Output
('PointAddress', -117.19568252432872, 34.05723700023128)

On the other hand, if querying for an attribute key that is not in out_fields, then the user will see KeyError shown as what's being returned here:

Input
esrihq2[0]['attributes']['Postal']
---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
<ipython-input-78-c83a961fdcfb> in <module>
----> 1 esrihq2[0]['attributes']['Postal'], esrihq2[0]['attributes']['Xmin'], esrihq2[0]['attributes']['Ymin']

KeyError: 'Postal'

source_country parameter

source_country limits the returned candidates to the specified country or countries for either single-field or multifield requests. Three-character country codes are the acceptable values for this parameter. A list of supported countries and codes is available in Geocode coverage. Multiple country codes can be specified (comma-separated with no spaces) to return results for more than one country.

Example

sourceCountry=FRA,DEU,ESP

lang_code parameter

lang_code sets the language in which geocode results are returned. This is useful for ensuring that results are returned in the expected language. If the langCode parameter isn't included in a request, or if it is included but there are no matching features with the input language code, then the resultant match is returned in the language code of the primary matched components from the input search string. See the table of supported countries for more information and valid language code values in each country. Note that full language names cannot be used in the lang_code parameter.

Example

langCode=fr

Now let's look at an example of geocoding at 'Western Wall'. We will specify the geocode to be performed inside the country of Israel and to return the results in Hebrew.

Input
# when `lang_code` is not set, default to return results in English
western_wall_en = geocode("Western Wall", source_country = "ISR")
western_wall_en[0]['attributes']['LongLabel']
Output
'The Western Wall, Rahvat HaKotel, Yerushalayim, ISR'
Input
western_wall = geocode("Western Wall", source_country = "ISR", lang_code="HE")
western_wall[0]['attributes']['LongLabel']
Output
'הכותל המערבי, רחבת הכותל, ירושלים'

Similarly, here we revisit a previous example of geocoding at 'Taj Mahal', only this time, we also specify the geocode to be performed inside the country of India and to return the result in Hindi:

Input
# when `lang_code` is not set, default to return results in English
taj_ind_en = geocode("Taj Mahal", source_country="IND")
taj_ind_en[0]['attributes']['LongLabel']
Output
'Taj Mahal, Taj Ganj, Agra, Uttar Pradesh, 282001, IND'
Input
taj_ind = geocode("Taj Mahal", source_country="IND", lang_code="HI")
taj_ind[0]['attributes']['LongLabel']
Output
'ताज महल, ताज गंज, आगरा, उत्तर प्रदेश, 282001, IND'

match_out_of_range parameter

The match_out_of_range parameter provides better spatial accuracy for inexact street addresses by specifying whether matches should be returned when the input number is outside of the house range defined for the input street. Out of range matches will be defined as Addr_type=StreetAddressExt. Input house numbers that exceed the range on a street segment by more than 100 will not result in streetAddressExt matches. For streets with smaller house numbers, the maxOutOfRange tolerance is less than 100. The default value of this parameter is true. Check out more on this topic at Esri Community.

Values: True | False

When match_out_of_range is not set or set to True, geocode will need to include the inexact estreet addresses as matched results. When set to False, then the results outside of the house range can be excluded.

Input
res_list = geocode("109 Main Street, Fairfax, VA", match_out_of_range=False)
print(len(res_list), " potential matches:")
for res in res_list:
    print(res['attributes']['LongLabel'], " | ", res['attributes']['Addr_type'])
20  potential matches:
Main St, Fairfax, VA, 22032, USA  |  StreetName
Main St, Fairfax, VA, 22031, USA  |  StreetName
Main St, Fairfax, VA, 22030, USA  |  StreetName
Main St, Alexandria, VA, 22309, USA  |  StreetName
Main St, Clifton, VA, 20124, USA  |  StreetName
109 Main St, Fairfax, IA, 52228, USA  |  StreetAddress
109 S Main St, Fairfax, OK, 74637, USA  |  StreetAddress
109 N Main St, Fairfax, OK, 74637, USA  |  StreetAddress
109 E Main St, Fairfax, MO, 64446, USA  |  StreetAddress
109 Main St W, Fairfax, SC, 29827, USA  |  StreetAddress
109 Main St E, Fairfax, SC, 29827, USA  |  StreetAddress
109 Main Dr, Fairfax, SC, 29827, USA  |  StreetAddress
Main Dr, Herndon, VA, 20170, USA  |  StreetName
The Main Street Pub, 7140 Main St, Clifton, VA, 20124, USA  |  POI
MainStreet Bank, 4029 Chain Bridge Rd, Fairfax, VA, 22030, USA  |  POI
MainStreet Bank, 10089 Fairfax Blvd, Fairfax, VA, 22030, USA  |  POI
Main Street OB Gyn, 10875 Main St, Fairfax, VA, 22030, USA  |  POI
Main Street Shell, 9956 Main St, Fairfax, VA, 22031, USA  |  POI
109 Main St, Cambridge, VT, 05444, USA  |  StreetAddress
MainStreet Bank, 1354 Old Chain Bridge Rd, Mc Lean, VA, 22101, USA  |  POI

location_type parameter

The location_type parameter specifies whether the rooftop point or street entrance should be the output geometry of PointAddress matches. By default, street is used, which can be useful for routing scenarios, as the rooftop location of some addresses may be offset from a street by a large distance. However, for map display purposes, it may be desirable to use rooftop instead, especially when large buildings or landmarks are geocoded.

The location parameter only affects the location object in the JSON response and does not change the x,y or DisplayX/DisplayY attribute values.

As what will see in the example below, when location_type="rooftop", map rendering of the specific point uses rooftop, which reflects the detailed location of PointAddress better. When location_type="street", map rendering of the returned geocoded result usually polts the point at the street.

Input
res_fset = geocode("380 New York St, 92373", location_type="rooftop", as_featureset=True)
Input
res_fset2 = geocode("380 New York St, 92373", location_type="street", as_featureset=True)
Input
from ipywidgets import HBox, VBox, Label, Layout

# create 3 map widgets
map1 = gis.map("Redlands, CA", 14)
map2 = gis.map("Redlands, CA", 14)

# set hbox layout preferences
hbox_layout = Layout()
hbox_layout.justify_content = 'space-around'

# create 2 hbox - one for title, another for maps
hb1 = HBox([Label('rooftop'),Label('street')])
hb2 = HBox([map1, map2])
hb1.layout,hb2.layout = hbox_layout, hbox_layout

# sync all maps
map1.sync_navigation(map2)

# each hbox is a row in the vbox
VBox([hb1,hb2])
Output
Input
map1.draw(res_fset) #shown on the left panel, as point on the rooftop of a building
map2.draw(res_fset2) #shown on the right, as point at the street

Commonly Seen Errors

Error messages (and/or error codes) are returned when the geocoding service cannot complete a request. This can be due to invalid parameters being included in the request or insufficient user permissions. Some potential errors that may be encountered with the service are described below.

  • Exception: Invalid Token (Error Code: 498) Possible causes:

    • The token associated with the current GIS object might be expired or invalid. You can try signing in to the GIS object again.
  • Unable to complete operation (Error Code: 400) Possible causes:

    • <parameter name> parameter value exceeds the maximum length of <maximum length> characters allowed for the parameter value. This error is returned if the input parameter value contains too many characters. For example, if the SingleLine parameter value exceeds 100 characters, this error is returned.
    • Category parameter value entered is not supported This error is returned when an invalid category parameter value is included in a request.
  • Cannot perform query. Invalid query parameters. (Error Code: 400) Possible causes:

    • Unable to find address for the specified location. Returned when no match can be found for a reverseGeocode operation.
  • Invalid or missing input parameters. (Error Code: 400)
    Possible causes:

    • This error is returned if a request is missing a required parameter.

Other error messages can be found in the help on geocoding service output.

Conclusions

In Part 2, we have walked through various approaches of performing geocode() to locate addresses using single line address, or multi-field address, with or without advanced parameters. Next in Part 3, we will talk about how to geocode point of interests.

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