Using the geocode() function

Search for street addresses

You can search for a street address, street name, or street intersection using the geocode() method. For best results, you should include as much location information as possible in the search in addition to the street address. See the section entitled Match accuracy for more information about obtaining optimal results for address searches.

You can pass the address components as a single address string or separated into multiple parameters using a dict. Examples of each are shown. Note that in each case the response is the same for both the single and multiple parameter addresses.

Example: Find a street address (380 New York Street, Redlands, CA 92373)

Single line address:

In [17]:
single_line_address = "380 New York Street, Redlands, CA 92373"
In [18]:
map = gis.map("Redlands, CA")
map

sample output

In [19]:
# geocode the single line address and plot the location of the first geocode result on the map

esrihq = geocode(single_line_address)[0]
popup = { 
    "title" : "Esri Headquarters", 
    "content" : esrihq['address']
    }
map.draw(esrihq['location'], popup)

Example: plot an address using a multiple field address

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.

In [20]:
multi_field_address = { 
    "Address" : "380 New York Street",
    "City" : "Redlands",
    "Region" : "CA",
    "Postal" : 92373
    }
In [21]:
map = gis.map("Redlands, CA")
map

sample output

In [22]:
#geocode the multiple field address and plot the location of the first geocode result on the map

esrihq = geocode(multi_field_address)[0]
popup = { 
    "title" : "Esri Headquarters", 
    "content" : esrihq['address']
    }
map.draw(esrihq['location'], popup)

Example: Search for a street intersection

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.

In [23]:
intersection = "redlands blvd and new york st 92373"
In [24]:
multi_field_intersection = { 
    "Address" : "redlands blvd & new york st",
    "City" : "Redlands",
    "Region" : "CA"
    }
In [25]:
map = gis.map("Esri, Redlands, CA", 15)
map

sample output

In [26]:
# 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]

popup = { 
    "title" : "redlands blvd and new york st", 
    "content" : intersection_result['address']
        }
map.draw(intersection_result['location'], popup)

Search for Points of Interests (POIs)

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 geocode method supports geocoding POIs by name or by type.

The supported types are listed in this table.

As with street addresses, you can search for POIs with findAddressCandidates using the single field or multifield approach.

To search for POIs with a single field search, use the singleLine parameter. In general, valid singleLine POI search strings can be formatted in variations of two basic structures:

  1. <name or type> <optional connector> <optional zone>
  2. <optional zone> <name or type> Where:

  3. <name or type> = A place name, such as "Disneyland", "Starbucks", "Niagra Falls", or "Paris"; or a type, such as "amusement parks", "waterfalls", or "coffee shops"

  4. <optional zone> = A zone—which can be a city, state or region, country, or any combination thereof—provides a spatial boundary to the search; it can be included to limit matching candidates but is not required
  5. <optional connector> = "in", "at", or "near"; this is not required for the search

Examples of valid single line address search strings include:

Business name searches:

  • Starbucks San Diego
  • Starbucks San Diego CA
  • Starbucks San Diego USA
  • Starbucks in San Diego
  • San Diego Starbucks
  • San Diego CA Starbucks
  • San Diego USA Starbucks

Type searches:

  • coffee shops San Diego
  • coffee shops San Diego CA
  • coffee shops San Diego USA
  • coffee shops in San Diego CA
  • San Diego coffee shops
  • San Diego CA coffee shops
  • San Diego USA coffee shops

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 neighborhood, city, subregion, region, and countryCode parameters.

Note: The postal and postalExt parameters are not valid input for POI searches.

General information

It is important to note that instead of providing a zone, you can limit searches to a specific area by using the searchExtent parameter. You can also influence the sorting of match candidates according to their proximity to a location with the location and distance parameters.

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 just search for hotels without qualifying information such as zone, search extent, or location, then 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.

Note: There may be instances when searches yield unexpected results. For example, a search for New York pizza, where the expected results are pizzerias in New York City, may instead return a match to a restaurant named New York Pizza in Sacramento, California. This is because exact place name matches are given higher priority to increase performance. If this occurs, you can obtain the desired results by modifying the search string—in this case, a search for pizza in NYC should yield the expected results.

Note: The address, phone number, and website URL of a POI can be returned by including outFields=Place_addr,Phone,URL in the request. But not all POIs have address, phone, and URL values associated with them.

Example: Find a business name (Starbucks Sydney AUS)

In [27]:
starbucks_sydney = "starbucks sydney AUS"

We can use either the single line address above, or the multiple field address below to search.

In [28]:
starbucks_sydney = {
    "Address": "starbucks",
    "City": "Sydney",
    "CountryCode": "AUS"
    }
In [29]:
map = gis.map("Sydney, AUS", 14)
map

sample output

In [30]:
starbucks = geocode(starbucks_sydney)
for starbuck in starbucks:
    map.draw(starbuck['location'])

Example: Find a business type (hotels Miami, FL)

In [31]:
address = "hotels miami FL"

We can use either the single line address above, or the multiple field address below to search.

In [32]:
address = {
    "Address": "hotels",
    "City": "miami",
    "Region": "FL"
    }
In [33]:
map = gis.map("Miami, Florida", 10)
map

sample output

In [34]:
miamihotels = geocode(address)
for hotel in miamihotels:
    map.draw(hotel['location'])

Search for administrative place names

The geocode method 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 World 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 London, so a search for "London" results in several equivalent matches; London, UK will always be the top candidate since it has the greatest population.

Example: Find a city name (London)

In [35]:
address = "London"
In [36]:
map = gis.map("United Kingdon", 5)
map

sample output

In [37]:
london = geocode(address)[0]
In [38]:
map.draw(london['location'])

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, Alabama, it is necessary to add the state information to the search.

Example: Search for city, state (Oxford, AL)

In [39]:
address = "Oxford AL"

Either the single line address above or the multiple field address below can be used to search for Oxford, AL.

In [40]:
address = {
    "Address" : "Oxford",
    "Region" : "AL"
}
In [41]:
map = gis.map("Alabama, United States")
map

sample output

In [42]:
oxford = geocode(address)[0]
map.draw(oxford['location'])

Search for postal codes

The geocode method 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 (110085 India)

In [43]:
address = {
    "Postal" : 110001,
    "CountryCode" : "India"
}
In [44]:
map = gis.map("New Delhi, India")
map

sample output

In [45]:
pincode = geocode(address)[0]
map.draw(pincode['location'])

The matched address contains several attributes, that provide values for the various output fields supported by the geocoder.

In [46]:
pincode['attributes']
Out[46]:
{'AddBldg': '',
 'AddNum': '',
 'AddNumFrom': '',
 'AddNumTo': '',
 'Addr_type': 'Postal',
 'City': '',
 'Country': 'IND',
 'DisplayX': 77.226595,
 'DisplayY': 28.622481,
 'Distance': 0,
 'LangCode': '',
 'Loc_name': 'IND.Postal',
 'Match_addr': '110001',
 'Nbrhd': '',
 'Phone': '',
 'PlaceName': '',
 'Place_addr': '',
 'Postal': '110001',
 'PostalExt': '',
 'Rank': '',
 'Region': '',
 'Score': 100,
 'Side': '',
 'StAddr': '',
 'StDir': '',
 'StName': '',
 'StPreDir': '',
 'StPreType': '',
 'StType': '',
 'Subregion': '',
 'Type': '',
 'URL': '',
 'X': 77.226595,
 'Xmax': 77.25453,
 'Xmin': 77.19862,
 'Y': 28.622481,
 'Ymax': 28.641,
 'Ymin': 28.60405}

Specify output fields

The geocode method allows you to specify individual output fields or return all output fields. The outFields parameter is used for this. If you want to return all supported output fields, use the default i.e. outFields=*; If you want to return specific fields, pass the desired field names as comma separated values, such as outFields=PlaceName,Type,City,Country, which returns the name, feature type, city, and country for a POI search.

See the topic Service output for detailed information about the attribute fields returned by the geocode method.

Example: Specify individual outfields for a POI search (PlaceName,Type,City,Country)

In [47]:
matches = geocode("coffee shops austin", out_fields="PlaceName,Type,City,Country")

The returned attributes only contain the key-value pairs for the specified output fields:

In [48]:
matches[0]['attributes']
Out[48]:
{'City': 'Austin',
 'Country': 'USA',
 'PlaceName': 'Starbucks',
 'Type': 'Coffee Shop'}

Feedback on this topic?