Geocodio OCD

Geocodio OCD is a lightweight Ruby wrapper around the geocod.io API (v1.12) with OCD IDs, Canadian, and UK political district support. It's a fork from https://github.com/davidcelis/geocodio (API v1.2)

Installation

In your Gemfile:

gem 'geocodio-ocd'

Usage

The point of entry to geocod.io's API is the Geocodio::Client class. Initialize one by passing your API key or allowing the initializer to automatically use the GEOCODIO_API_KEY environment variable:

geocodio = Geocodio::Client.new('0123456789abcdef')

# Or, if you've set GEOCODIO_API_KEY in your environment:
geocodio = Geocodio::Client.new

Geocoding

The Geocodio::Client#geocode method is used to request coordinates and expanded information on one or more addresses. It accepts an array of addresses and an options hash. If more than one address is provided, #geocode will use Geocodio's batch endpoint behind the scenes. It is possible for a geocoding request to yield multiple results with varying degrees of accuracy, so the geocode method will always return one Geocodio::AddressSet for each query made:

results = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014'])
# => #<Geocodio::AddressSet:0x007fdf23a07f80 @query="1 Infinite Loop, Cupertino, CA 95014", @addresses=[...]>

AddressSets are enumerable, so you can iterate over each result and perform operations on the addresses:

results.each { |address| puts address }

If you just want the most accurate result, use the #best convenience method:

address = results.best
# => #<Geocodio::Address:0x007fb062e7fb20 @number="1", @street="Infinite", @suffix="Loop", @city="Monta Vista", @state="CA", @zip="95014", @latitude=37.331669, @longitude=-122.03074, @accuracy=1, @formatted_address="1 Infinite Loop, Monta Vista CA, 95014">

puts address
# => 1 Infinite Loop, Cupertino CA, 95014

puts address.latitude # or address.lat
# => 37.331669

puts address.longitude # or address.lng
# => -122.03074

To perform a batch geocoding operation as mentioned earlier, simply add more addresses to the passed array:

result_sets = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014', '54 West Colorado Boulevard, Pasadena, CA 91105'])
# => [#<Geocodio::AddressSet:0x007fdf23a07f80 @query="1 Infinite Loop, Cupertino, CA 95014", @addresses=[...]>, #<Geocodio::AddressSet:0x007fdf23a07f80 @query="54 West Colorado Boulevard, Pasadena, CA 91105", @addresses=[...]>]

cupertino = result_sets.first.best
# => #<Geocodio::Address:0x007fb062e7fb20 @number="1", @street="Infinite", @suffix="Loop", @city="Monta Vista", @state="CA", @zip="95014", @latitude=37.331669, @longitude=-122.03074, @accuracy=1, @formatted_address="1 Infinite Loop, Monta Vista CA, 95014">

Reverse Geocoding

The interface to reverse geocoding is very similar to geocoding. Use the Geocodio::Client#reverse_geocode method (aliased to Geocodio::Client#reverse) with one or more pairs of coordinates:

addresses = geocodio.reverse_geocode(['37.331669,-122.03074'])
# => #<Geocodio::AddressSet:0x007fdf23a07f80 @query="1 Infinite Loop, Cupertino, CA 95014", @addresses=[...]>

address_sets = geocodio.reverse_geocode(['37.331669,-122.03074', '34.145760590909,-118.15204363636'])
# => [#<Geocodio::AddressSet:0x007fdf23a07f80 @query="1 Infinite Loop, Cupertino, CA 95014", @addresses=[...]>, #<Geocodio::AddressSet:0x007fdf23a07f80 @query="54 West Colorado Boulevard, Pasadena, CA 91105", @addresses=[...]>]

Coordinate pairs can also be specified as hashes:

address_sets = geocodio.reverse_geocode([{ lat: 37.331669, lng: -122.03074 }, { latitude: 34.145760590909, longitude: -118.15204363636 }])
# => [#<Geocodio::AddressSet:0x007fdf23a07f80 @query="1 Infinite Loop, Cupertino, CA 95014", @addresses=[...]>, #<Geocodio::AddressSet:0x007fdf23a07f80 @query="54 West Colorado Boulevard, Pasadena, CA 91105", @addresses=[...]>]

Parsing

address = geocodio.parse('1 Infinite Loop, Cupertino, CA 95014')
# => #<Geocodio::Address:0x007fa3c15f41c0 @number="1", @street="Infinite", @suffix="Loop", @city="Cupertino", @state="CA", @zip="95014", @accuracy=nil, @formatted_address="1 Infinite Loop, Cupertino CA, 95014">

Note that this endpoint performs no geocoding; it merely formats a single provided address according to geocod.io's standards.

Additional fields

Geocodio has added support for retrieving additional fields when geocoding or reverse geocoding. To request these fields, pass an options hash to either #geocode or #reverse_geocode. Possible fields include or cd113,( or cd to get current legislators), stateleg, stateleg-next, school, and timezone, Open Civic Data Division Identifiers (OCD-IDs) cd118 and stateleg-next are required.

address = geocodio.geocode(['54 West Colorado Boulevard Pasadena CA 91105'], fields: %w[cd118 stateleg-next school timezone]).best

address.congressional_districts
# => #<Geocodio::CongressionalDistrict:0x007fa3c15f41c0 @name="Congressional District 27" @district_number=27 @congress_number=113 @congress_years=2013..2015>

address.house_districts
# => [#<Geocodio::StateLegislativeDistrict:0x007fa3c15f41c0 @name="Assembly District 41" @district_number=41>]

address.senate_districts
# => [#<Geocodio::StateLegislativeDistrict:0x007fa3c15f41c0 @name="State Senate District 25" @district_number=25>]

address.unified_school_district # or .elementary_school_district and .secondary_school_district if not unified
# => #<Geocodio::SchoolDistrict:0x007fa3c15f41c0 @name="Pasadena Unified School District" @lea_code="29940" @grade_low="KG" @grade_high="12">

address.timezone
# => #<Geocodio::Timezone:0x007fa3c15f41c0 @name="PST" @utc_offset=-8 @observes_dst=true>
address.timezone.observes_dst?
# => true

UK political districts

To fetch UK Westminster, devolved, and local government districts, pass country: 'GB' along with one or more of the UK field appends: uk-westminster, uk-devolved, uk-local. Each also has a -next variant (e.g. uk-westminster-next) that returns upcoming boundary changes.

address = geocodio.geocode(
  ['10 Downing St, London SW1A 2AA'],
  fields: %w[uk-westminster uk-devolved uk-local],
  country: 'GB'
).best

address.uk_westminster
# => [#<Geocodio::UK::District @district_type="westminster_constituency"
#       @gss_code="E14001172"
#       @ocd_id="ocd-division/country:gb/part:eng/region:uki/ed:cities_of_london_and_westminster"
#       @name="Cities of London and Westminster" @nation="ENG">]

address.uk_westminster.first.ocd_id
# => "ocd-division/country:gb/part:eng/region:uki/ed:cities_of_london_and_westminster"

address.uk_devolved
# => []  # empty for English addresses; Scotland returns 2 rows, Wales 1-2, NI 1

address.uk_local
# => [#<Geocodio::UK::District @district_type="ward" @gss_code="E05013806" @name="St James's" @nation="ENG">]

address.uk_local.first.gss_code   # canonical UK government identifier, always present
# => "E05013806"

address.uk_local.first.ocd_id     # nil for local rows — OCD does not cover UK wards
# => nil

address.uk_westminster.first.upcoming_district?
# => false

Each Geocodio::UK::District object exposes: district_type, gss_code, ocd_id, name, nation, is_upcoming_district, source, and upcoming_district?.

OCD ID coverage notes:

uk-westminster: ocd_id always present and non-nil (100% coverage)
uk-devolved: ocd_id present in payload but may be nil (partial coverage; Scottish Parliament ~10%, Senedd regions 0%)
uk-local: ocd_id is always nil — use gss_code as the canonical identifier for wards and county electoral divisions

Canadian address

To fetch Canadian federal and provincial electoral districts, pass provriding and riding to the fields input parameter. From the result, check if the Canadian data is available by method Address#canadian? then get the districts data from method Address#canadian as following:

address = geocodio.geocode(['160 Spadina Ave., Toronto, ON M5T 2C2, Canada'], 
  fields: %w[cd118 stateleg-next school timezone]).best

address.canadian?
# => true

address.canadian.federal_electoral_district
# => #<Geocodio::Canadian::FederalElectoralDistrict:0x00007f9c173ff358
#  @code="35101",
#  @name_english="Spadina--Fort York",
#  @name_french="Spadina--Fort York",
#  @ocd_id="ocd-division/country:ca/ed:35101-2013",
#  @source="Statistics Canada">

address.canadian.provincial_electoral_district
#<Geocodio::Canadian::ProvincialElectoralDistrict:0x00007fd9001046a0
#  @name_english="University - Rosedale",
#  @name_french="University - Rosedale",
#  @ocd_id="ocd-division/country:ca/province:on/ed:112-2015",
#  @source="Elections Ontario">

Contributing

Fork it ( https://github.com/shairontoledo/geocodio-ocd/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

geocodio-ocd

Development

Runtime