Single address geocoding¶

Import the API client and ensure you have a valid API key:

>>> from geocodio import GeocodioClient
>>> client = GeocodioClient(MY_KEY)
>>> geocoded_location = client.geocode("42370 Bob Hope Drive, Rancho Mirage CA")

The result from the Geocod.io service is a dictionary including your query, its components, and a list of matching results:

>>> geocoded_location
{
  "input": {
    "address_components": {
      "number": "42370",
      "street": "Bob Hope",
      "suffix": "Dr",
      "city": "Rancho Mirage",
      "state": "CA"
    },
    "formatted_address": "42370 Bob Hope Dr, Rancho Mirage CA"
  },
  "results": [
    {
      "address_components": {
        "number": "42370",
        "street": "Bob Hope",
        "suffix": "Dr",
        "city": "Rancho Mirage",
        "state": "CA",
        "zip": "92270"
      },
      "formatted_address": "42370 Bob Hope Dr, Rancho Mirage CA, 92270",
      "location": {
        "lat": 33.738987255507,
        "lng": -116.40833849559
      },
      "accuracy": 1
    },
    {
      "address_components": {
        "number": "42370",
        "street": "Bob Hope",
        "suffix": "Dr",
        "city": "Rancho Mirage",
        "state": "CA",
        "zip": "92270"
      },
      "formatted_address": "42370 Bob Hope Dr, Rancho Mirage CA, 92270",
      "location": {
        "lat": 33.738980796909,
        "lng": -116.40833917329
      },
      "accuracy": 0.8
    }
  ]
}

This returned several geolocation results in descending order of accuracy, so the first and most accurate geocoded location latitude and longitude can be accessed using the coords attribute:

>>> geocoded_location.coords
(-116.40833849559, 33.738987255507)

Batch geocoding¶

You can also geocode a list of addresses:

>>> geocoded_addresses = geocodio.geocode(['1600 Pennsylvania Ave, Washington, DC',
        '3101 Patterson Ave, Richmond, VA, 23221'])

Return just the coordinates for the list of geocoded addresses:

>>> geocoded_addresses.coords
[(-116.40833849559, 33.738987255507), (-116.40833849559, 33.738987255507)]

Lookup an address by formatted address:

>>> geocoded_addresses.get('1600 Pennsylvania Ave, Washington, DC').coords
(-116.40833849559, 33.738987255507)

Note that to perform the key based lookup you must use the get method. This preserves the list’s index based lookup.

{
    "query": "",
    "response": {
        "error": "Could not parse address"
    }
}

Single point reverse-geocoding¶

Reverse geocoding:

>>> client.reverse((33.738987, -116.4083))

Batch reverse-geocoding¶

You can also reverse geocode in batch:

>>> client.reverse([(33.738987, -116.4083), (34.288, -112.12)])

As with geocoding, there is a limit of 10,000 points you can geocode at a time.

Address¶

An Address object is just a dictionary object that provides two access methods for returning the accuracy value of the geocoded address as an attribute and the coordinates of the address as an attribute.

Address.__init__(results_list, order='lat')¶

results_list is the raw data

order allows you to change the default order of the coordinate points. Setting order to ‘lng’ or any value other than ‘lat’ will return the points in (longitude, latitude) order.

Address.coords()¶

A property method that returns the coordinates of the address or None if they are not available (in the case of a parsed address).

Address.accuracy()¶

A property method that returns the accuracy rating of the geocoded address.

When parsing an address, the result is returned as an Address for consistency, but the result’s usefullness will be limited to the dictionary structure.

Location¶

A Location object is a dictionary object that provides the same access methods as an Address object. Because a geocoded Location may have more than one address returned, the methods refer to the coordinates and accuracy respectively of the most most accurate geocoded address.

Location.__init__(results_dict, order='lat')¶

results_dict is the raw data

order allows you to change the default order of the coordinate points. Setting order to ‘lng’ or any value other than ‘lat’ will return the points in (longitude, latitude) order.

Location.coords()¶

A property method that returns the coordinates of the best matched address or None if they are not available.

Location.accuracy()¶

A property method that returns the accuracy rating of the best matched address.

LocationCollection¶

A LocationCollection object is a list of Location objects. It maintains an internal dictionary of each geocoding or reverse geocoding query with reference to the list index of the result. This allows the order of the list to be preserved but for simple lookup of the values without needing to iterate over the entire list.

LocationCollection.get(key)¶

A method that returns a Location object from the list of locations by checking against the query input.

The key can be the queried address as a string (geocoding) or the queried point (reverse geocoding). The point can be provided as a tuple of floats:

(33.12, -78.123)

a tuple of float-coerceable values (e.g. a float as a string):

("33.12", "-78.123")

or a string representing the query:

"33.12, -78.123"

This method is provided instead of overriding the __getitem__ method as the latter allows index based access to the list.

LocationCollection.coords()¶

A property method that returns a list of all of the coordinates