The Geocodio API offers a number of different field appends that allow you to add additional datasets to your results. This includes information about Congressional Districts, School Districts, Census Identifiers, Time Zones, ZIP+4 and so much more.
In this article, we will discuss how to append fields in a number of different circumstances, including forward, reverse and batch geocoding.
If you need more information about how to install the Geocodio Gem or geocode without appending fields, check out these articles, which discuss those topics in more detail:
How To Geocode A Single Address Using A Ruby Library
How To Reverse Geocode A Pair of Coordinates Using A Ruby Library
How To Batch Geocode Using A Ruby Library
Note:
Remember that each field append that you add to your result counts as a lookup for each address or coordinate pair that you geocode. For example, if you were to batch geocode 20 addresses and append Time Zone information, that would count as 40 lookups. If you were to do the same, but append both Time Zones and ZIP+4, that would count as 60 lookups.
Let’s start by appending Time Zones to a single address.
After requiring ‘geocodio/gem’ and creating an instance of Geocodio::Gem by assigning it to the variable geocodio, call the .geocode() method on that variable and pass in a string containing the address. Be sure to wrap that string in square brackets ([ ]).
It should look like this:
require ‘geocodio/gem’
geocodio = Geocodio::Gem.new(“YOUR API KEY”)
results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201"])
To include the Time Zones field append, add a new array after the array containing your address. Separate them with a comma. In that new array, pass in a string containing the code for the type of field append you’d like to include. In this case we’ll use timezone.
results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201"], ["timezone"])
results # => {"input"=>{"address_components"=>{"number"=>"1109", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1109 N Highland St, Arlington, VA 22201"}, "results"=>[{"address_components"=>{"number"=>"1109", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1109 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.886672, "lng"=>-77.094735}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Arlington", "fields"=>{"timezone"=>{"name"=>"America/New_York", "utc_offset"=>-5, "observes_dst"=>true, "abbreviation"=>"EST", "source"=>"© OpenStreetMap contributors"}}}]}
You can see that the response from the API includes a new “fields” key that contains the information about the address’ time zone.
There are a number of different appends codes that you can use within the second array, including:
| Code | Append Type |
|---|---|
| cd | Congressional District |
| stateleg | State-Level District |
| school | School District |
| census | Census Identifiers (Census Tracts/Blocks, FIPS, etc) |
| acs-demographics | Demographics |
| acs-economics | Economics |
| acs-families | Families |
| acs-housing | Housing |
| acs-social | Social: Education and Veteran Status |
| zip4 | USPS ZIP+4 and Delivery Information |
| riding | Canadian Federal Electoral District |
| provriding | Canadian Provincial/Territorial Electoral District |
| statcan | Canadian Statistical Boundaries |
| timezone | Timezone |
Find additional appends codes in our API documentation.
You can append more than one field to your results. To do so, include an additional appends code in your fields array. Be sure it is added in a unique string that is separated by a comma.
For example, let’s reverse geocode a pair of coordinates and append Congressional District and State-Level District data to our returned JSON. Here’s what that would look like.
results = geocodio.reverse(['38.886672,-77.094735'], ['cd', 'stateleg'])
results # => {"input": {"address_components": {"number": "1109", "predirectional": "N", "street": "Highland", "suffix": "St", "formatted_street": "N Highland St", "city": "Arlington", "state": "VA", "country": "US"}, "formatted_address": "1109 N Highland St, Arlington, VA"}, "results": [{"address_components": {"number": "1109", "predirectional": "N", "street": "Highland", "suffix": "St", "formatted_street": "N Highland St", "city": "Arlington", "county": "Arlington County", "state": "VA", "zip": "22201", "country": "US"}, "formatted_address": "1109 N Highland St, Arlington, VA 22201", "location": {"lat": 38.886672, "lng": -77.094735}, "accuracy": 1, "accuracy_type": "rooftop", "source": "Arlington", "fields": {"congressional_districts": [{"name": "Congressional District 8", "district_number": 8, "ocd_id": "ocd-division/country:us/state:va/cd:8", "congress_number": "118th", "congress_years": "2023-2025", "proportion": 1, "current_legislators": [{"type": "representative", "bio": {"last_name": "Beyer", "first_name": "Donald", "birthday": "1950-06-20", "gender": "M", "party": "Democrat"}, "contact": {"url": "https://beyer.house.gov", "address": "1119 Longworth House Office Building Washington DC 20515-4608", "phone": "202-225-4376", "contact_form": null}, "social": {"rss_url": null, "twitter": "RepDonBeyer", "facebook": "RepDonBeyer", "youtube": null, "youtube_id": "UCPJGVbOVcAVGiBwq8qr_T9w"}, "references": {"bioguide_id": "B001292", "thomas_id": "02272", "opensecrets_id": "N00036018", "lis_id": null, "cspan_id": "21141", "govtrack_id": "412657", "votesmart_id": "1707", "ballotpedia_id": "Don Beyer", "washington_post_id": null, "icpsr_id": "21554", "wikipedia_id": "Don Beyer"}, "source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"}, {"type": "senator", "bio": {"last_name": "Warner", "first_name": "Mark", "birthday": "1954-12-15", "gender": "M", "party": "Democrat"}, "contact": {"url": "https://www.warner.senate.gov", "address": "703 Hart Senate Office Building Washington DC 20510", "phone": "202-224-2023", "contact_form": "https://www.warner.senate.gov/public/index.cfm?p=Contact”}, "social": {"rss_url": "http://www.warner.senate.gov/public/?a=rss.feed", "twitter": "MarkWarner", "facebook": "MarkRWarner", "youtube": "SenatorMarkWarner", "youtube_id": "UCwyivNlEGf4sGd1oDLfY5jw"}, "references": {"bioguide_id": "W000805", "thomas_id": "01897", "opensecrets_id": "N00002097", "lis_id": "S327", "cspan_id": "7630", "govtrack_id": "412321", "votesmart_id": "535", "ballotpedia_id": "Mark Warner", "washington_post_id": null, "icpsr_id": "40909", "wikipedia_id": "Mark Warner"}, "source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"}, {"type": "senator", "bio": {"last_name": "Kaine", "first_name": "Timothy", "birthday": "1958-02-26", "gender": "M", "party": "Democrat”}, "contact": {"url": "https://www.kaine.senate.gov", "address": "231 Russell Senate Office Building Washington DC 20510", "phone": "202-224-4024", "contact_form": "https://www.kaine.senate.gov/contact"}, "social": {"rss_url": "http://www.kaine.senate.gov/rss/feeds/?type=all", "twitter": null, "facebook": "SenatorKaine", "youtube": "SenatorTimKaine", "youtube_id": "UC27LgTZlUnBQoNEQFZdn9LA"}, "references": { "bioguide_id": "K000384", "thomas_id": "02176", "opensecrets_id": "N00033177", "lis_id": "S362", "cspan_id": "49219", "govtrack_id": "412582", "votesmart_id": "50772", "ballotpedia_id": "Tim Kaine", "washington_post_id": null, "icpsr_id": "41305", "wikipedia_id": "Tim Kaine"}, "source": "Legislator data is originally collected and aggregated by https://github.com/unitedstates/"}]}], "state_legislative_districts": {"house": [{"name": "State House District 47", "district_number": "47", "ocd_id": "ocd-division/country:us/state:va/sldl:47", "is_upcoming_state_legislative_district": false, "proportion": 1}], "senate": [{"name": "State Senate District 31", "district_number": "31", "ocd_id": "ocd-division/country:us/state:va/sldu:31", "is_upcoming_state_legislative_district": false, "proportion": 1}]}}}]}
This example demonstrates two things:
First, you can see that the "fields" key returns two distinct datasets: congressional_districts and state_legislative_districts, exactly as requested. You can add as many appends code as you need, just remember that each one you include increases the number of lookups you will make.
Next, this displays how to append fields to the .reverse() method. It’s exactly the same process as when you use .geocode().
You can also append fields when batch geocoding. This looks very similar to individual calls. The only major difference is that in the first array, place a list of address or coordinate strings, and in the second array, place a list of appends codes.
It would be structured like this:
results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201", "12187 Darnestown Rd, Gaithersburg, MD 20878", "4961 Elm Street, Bethesda, MD"], [“cd”, “stateleg”])
That’s all there is to it! With these tools, you can easily implement the Geocodio Ruby Library to append data fields to your geocoded information.