Geocodio::Gem

Geocodio Gem is a library that allows you to make quick and easy API calls to the geocod.io API.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add geocodio-gem

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install geocodio-gem

Setup

To get started, initialize a Geocodio::Gem class by passing in your API Key. If you need to generate an API Key, you can do so by logging into your Geocodio account and navigating to the API Keys tab.

geocodio = Geocodio::Gem.new("YOUR_API_KEY")

Basic Usage

Geocoding

Forward geocoding takes an address and returns coordinates. Geocode a single address by using the Geocodio::Gem#geocode method. Pass in an address string within array brackets. We will parse the provided address and respond with a set of coordinates. Your results will return the most accurate locations first.

results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201"])

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"}]}

To batch geocode a group of addresses, pass multiple address strings into the array. The Gem will automatically recognize the batch request and make the appropriate call.

results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201", "12187 Darnestown Rd, Gaithersburg, MD 20878", "4961 Elm Street, Bethesda, MD"])

results # => {"results"=>[{"query"=>"1109 N Highland St, Arlington, VA 22201", "response"=>{"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"}]}}, {"query"=>"12187 Darnestown Rd, Gaithersburg, MD 20878", "response"=>{"input"=>{"address_components"=>{"number"=>"12187", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12187 Darnestown Rd, Gaithersburg, MD 20878"}, "results"=>[{"address_components"=>{"number"=>"12187", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12187 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118169, "lng"=>-77.251699}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12185", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12185 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118093, "lng"=>-77.25167}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12189", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12189 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118248, "lng"=>-77.251722}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12183", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12183 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.117998, "lng"=>-77.25164}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Montgomery"}]}}, {"query"=>"4961 Elm Street, Bethesda, MD", "response"=>{"input"=>{"address_components"=>{"number"=>"4961", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "state"=>"MD", "country"=>"US"}, "formatted_address"=>"4961 Elm St, Bethesda, MD"}, "results"=>[{"address_components"=>{"number"=>"4961", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4961 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982196, "lng"=>-77.098161}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"4959", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4959 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982198, "lng"=>-77.098084}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"4963", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4963 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.98239, "lng"=>-77.097993}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Statewide MD"}, {"address_components"=>{"number"=>"4963", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4963 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982195, "lng"=>-77.098244}, "accuracy"=>0.9, "accuracy_type"=>"nearest_rooftop_match", "source"=>"Montgomery"}]}}]}

Reverse Geocoding

Reverse geocoding takes a pair of coordinates and returns an address. Reverse geocode a single address by using the Geocodio::Gem#reverse method. Pass in a string that contains latitude and longitude separate by a comma. We will respond with an address associated with the coordinates. Your results will return the most accurate locations first.

    results = geocodio.reverse(["38.9002898,-76.9990361"])
    
    results # => {"results"=>[{"address_components"=>{"number"=>"508", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"508 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900432, "lng"=>-76.999031}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"510", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"510 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900429, "lng"=>-76.998965}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"506", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"506 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900437, "lng"=>-76.999099}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"504", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"504 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900422, "lng"=>-76.999169}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"512", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"512 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900435, "lng"=>-76.998897}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"500", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"500 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.999507}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"800", "street"=>"5th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"5th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"800 5th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.999507}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"817", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"817 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900203, "lng"=>-76.998442}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"774", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"774 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.900078, "lng"=>-76.998443}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"474", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"474 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900205, "lng"=>-76.99994}, "accuracy"=>0.44, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"540", "street"=>"I", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"I St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"540 I St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.998836}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"900", "street"=>"5th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"5th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"900 5th St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.999509}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"900", "street"=>"6th", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"6th St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"900 6th St NE, Washington, DC 20002", "location"=>{"lat"=>38.901323, "lng"=>-76.998446}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}

To batch geocode a multiple sets of coordinates, pass each latitude and longitude pair as a separate string into the array. The Gem will automatically recognize the batch request and make the appropriate call.

    results = geocode.reverse(["38.88674717512318, -77.09464642536076", "39.118308110111954, -77.2516753863881", "38.98237295882022, -77.09805507289941"])

    results # => {"results"=>[{"query"=>"38.88674717512318, -77.09464642536076", "response"=>{"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"}, {"address_components"=>{"number"=>"3030", "street"=>"Clarendon", "suffix"=>"Blvd", "formatted_street"=>"Clarendon Blvd", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3030 Clarendon Blvd, Arlington, VA 22201", "location"=>{"lat"=>38.886876, "lng"=>-77.094702}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Arlington"}, {"address_components"=>{"number"=>"3020", "street"=>"Clarendon", "suffix"=>"Blvd", "formatted_street"=>"Clarendon Blvd", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3020 Clarendon Blvd, Arlington, VA 22201", "location"=>{"lat"=>38.886969, "lng"=>-77.094529}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Virginia Geographic Information Network (VGIN)"}, {"address_components"=>{"number"=>"3108", "predirectional"=>"N", "street"=>"Washington", "suffix"=>"Blvd", "formatted_street"=>"N Washington Blvd", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3108 N Washington Blvd, Arlington, VA 22201", "location"=>{"lat"=>38.885773, "lng"=>-77.094955}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1027", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1027 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.885598, "lng"=>-77.09476}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"3059", "predirectional"=>"N", "street"=>"Washington", "suffix"=>"Blvd", "formatted_street"=>"N Washington Blvd", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3059 N Washington Blvd, Arlington, VA 22201", "location"=>{"lat"=>38.885574, "lng"=>-77.09456}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1079", "predirectional"=>"N", "street"=>"Hudson", "suffix"=>"St", "formatted_street"=>"N Hudson St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1079 N Hudson St, Arlington, VA 22201", "location"=>{"lat"=>38.885785, "lng"=>-77.095693}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"3100", "street"=>"10th", "suffix"=>"Rd", "postdirectional"=>"N", "formatted_street"=>"10th Rd N", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3100 10th Rd N, Arlington, VA 22201", "location"=>{"lat"=>38.8852, "lng"=>-77.094709}, "accuracy"=>0.42, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1015", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1015 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.885058, "lng"=>-77.094687}, "accuracy"=>0.41, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1014", "predirectional"=>"N", "street"=>"Hudson", "suffix"=>"St", "formatted_street"=>"N Hudson St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1014 N Hudson St, Arlington, VA 22201", "location"=>{"lat"=>38.884985, "lng"=>-77.095586}, "accuracy"=>0.41, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"3201", "street"=>"Washington", "suffix"=>"Blvd", "formatted_street"=>"Washington Blvd", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"3201 Washington Blvd, Arlington, VA 22201", "location"=>{"lat"=>38.885989, "lng"=>-77.096909}, "accuracy"=>0.41, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}}, {"query"=>"39.118308110111954, -77.2516753863881", "response"=>{"results"=>[{"address_components"=>{"number"=>"12191", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12191 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118326, "lng"=>-77.251749}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12189", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12189 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118248, "lng"=>-77.251722}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12193", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12193 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118376, "lng"=>-77.251707}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12187", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12187 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118169, "lng"=>-77.251699}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12185", "street"=>"Darnestown", "suffix"=>"Rd", "formatted_street"=>"Darnestown Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12185 Darnestown Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.118093, "lng"=>-77.25167}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"12184", "street"=>"State Hwy 28", "formatted_street"=>"State Hwy 28", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12184 State Hwy 28, Gaithersburg, MD 20878", "location"=>{"lat"=>39.117781, "lng"=>-77.252536}, "accuracy"=>0.44, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"15998", "street"=>"Quince Orchard", "suffix"=>"Rd", "formatted_street"=>"Quince Orchard Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"15998 Quince Orchard Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.117888, "lng"=>-77.25293}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"12182", "street"=>"McDonald Chapel", "suffix"=>"Dr", "formatted_street"=>"McDonald Chapel Dr", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12182 McDonald Chapel Dr, Gaithersburg, MD 20878", "location"=>{"lat"=>39.119427, "lng"=>-77.251898}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"15986", "street"=>"Quince Orchard", "suffix"=>"Rd", "formatted_street"=>"Quince Orchard Rd", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"15986 Quince Orchard Rd, Gaithersburg, MD 20878", "location"=>{"lat"=>39.117709, "lng"=>-77.253041}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"12218", "street"=>"State Hwy 28", "formatted_street"=>"State Hwy 28", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12218 State Hwy 28, Gaithersburg, MD 20878", "location"=>{"lat"=>39.117983, "lng"=>-77.253546}, "accuracy"=>0.42, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"12135", "street"=>"McDonald Chapel", "suffix"=>"Dr", "formatted_street"=>"McDonald Chapel Dr", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12135 McDonald Chapel Dr, Gaithersburg, MD 20878", "location"=>{"lat"=>39.119872, "lng"=>-77.25132}, "accuracy"=>0.42, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1036", "street"=>"State Hwy 124", "formatted_street"=>"State Hwy 124", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"1036 State Hwy 124, Gaithersburg, MD 20878", "location"=>{"lat"=>39.119961, "lng"=>-77.250987}, "accuracy"=>0.41, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"12114", "street"=>"State Hwy 28", "formatted_street"=>"State Hwy 28", "city"=>"Gaithersburg", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20878", "country"=>"US"}, "formatted_address"=>"12114 State Hwy 28, Gaithersburg, MD 20878", "location"=>{"lat"=>39.116996, "lng"=>-77.249917}, "accuracy"=>0.41, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}}, {"query"=>"38.98237295882022, -77.09805507289941", "response"=>{"results"=>[{"address_components"=>{"number"=>"4963", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4963 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.98239, "lng"=>-77.097993}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide MD"}, {"address_components"=>{"number"=>"4940", "street"=>"Hampden", "suffix"=>"Ln", "formatted_street"=>"Hampden Ln", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4940 Hampden Ln, Bethesda, MD 20814", "location"=>{"lat"=>38.982529, "lng"=>-77.098032}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"4959", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4959 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982198, "lng"=>-77.098084}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"4957", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4957 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982201, "lng"=>-77.098002}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Montgomery"}, {"address_components"=>{"number"=>"4962", "street"=>"Hampden", "suffix"=>"Ln", "formatted_street"=>"Hampden Ln", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4962 Hampden Ln, Bethesda, MD 20814", "location"=>{"lat"=>38.98247, "lng"=>-77.098252}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide MD"}, {"address_components"=>{"number"=>"4984", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4984 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982093, "lng"=>-77.097887}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"7300", "street"=>"Arlington", "suffix"=>"Rd", "formatted_street"=>"Arlington Rd", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"7300 Arlington Rd, Bethesda, MD 20814", "location"=>{"lat"=>38.982676, "lng"=>-77.098509}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"5000", "street"=>"Hampden", "suffix"=>"Ln", "formatted_street"=>"Hampden Ln", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"5000 Hampden Ln, Bethesda, MD 20814", "location"=>{"lat"=>38.982676, "lng"=>-77.098509}, "accuracy"=>0.46, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"7249", "street"=>"Arlington", "suffix"=>"Rd", "formatted_street"=>"Arlington Rd", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"7249 Arlington Rd, Bethesda, MD 20814", "location"=>{"lat"=>38.982036, "lng"=>-77.098479}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"5000", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"5000 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982036, "lng"=>-77.09848}, "accuracy"=>0.45, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"7400", "street"=>"Arlington", "suffix"=>"Rd", "formatted_street"=>"Arlington Rd", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"7400 Arlington Rd, Bethesda, MD 20814", "location"=>{"lat"=>38.98334, "lng"=>-77.098548}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"4919", "street"=>"Montgomery", "suffix"=>"Ln", "formatted_street"=>"Montgomery Ln", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4919 Montgomery Ln, Bethesda, MD 20814", "location"=>{"lat"=>38.983371, "lng"=>-77.097503}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"4956", "street"=>"Elm", "suffix"=>"St", "formatted_street"=>"Elm St", "city"=>"Bethesda", "county"=>"Montgomery County", "state"=>"MD", "zip"=>"20814", "country"=>"US"}, "formatted_address"=>"4956 Elm St, Bethesda, MD 20814", "location"=>{"lat"=>38.982138, "lng"=>-77.096655}, "accuracy"=>0.43, "accuracy_type"=>"nearest_street", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}}]}

Appending Fields

If you would like to append data fields to your results, you can do so by passing in a second array after the array that contains your addresses or coordinates. Be sure to separate these arrays by a comma. Within the second array, provide a string of the parameter name of the field you would like to append. For example, if you require timezones added to your results, you would use "timezone".

For a complete list of data field parameters, reference the Geocodio API documentation.

This will work for both the Geocodio::Gem#geocode and Geocodio::Gem#reverse methods.

   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"}}}]}

If you would like to append multiple data fields, pass each parameter that you require into the array as a separate string, divided by commas.

    results = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201"], ["timezone", "stateleg"])

    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"=>{"state_legislative_districts"=>{"house"=>[{"name"=>"State House District 47", "district_number"=>"47", "ocd_id"=>nil, "is_upcoming_state_legislative_district"=>false, "proportion"=>1}], "senate"=>[{"name"=>"State Senate District 31", "district_number"=>"31", "ocd_id"=>nil, "is_upcoming_state_legislative_district"=>false, "proportion"=>1}]}, "timezone"=>{"name"=>"America/New_York", "utc_offset"=>-5, "observes_dst"=>true, "abbreviation"=>"EST", "source"=>"© OpenStreetMap contributors"}}}]}

Limiting Results

Some results may return a collection of different possible matches to the address or coordinates you've provided. If you would like to limit the number of results you receive, you can add a limit parameter that will set a maximum amount of results to be returned.

Pass in the maximum amount of results you'd prefer after your fields array as a number.

    results = geocodio.geocode(["1120 N Highland St, Arlington, VA 22201"], [], 1)

    # => {"input"=>{"address_components"=>{"number"=>"1120", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1120 N Highland St, Arlington, VA 22201"}, "results"=>[{"address_components"=>{"number"=>"1120", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1120 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.886743, "lng"=>-77.095041}, "accuracy"=>1, "accuracy_type"=>"range_interpolation", "source"=>"TIGER/Line® dataset from the US Census Bureau"}]}

    results_two = geocodio.geocode(["1120 N Highland St, Arlington, VA 22201"], [], 3) 
    
    # => {{"input"=>{"address_components"=>{"number"=>"1120", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1120 N Highland St, Arlington, VA 22201"}, "results"=>[{"address_components"=>{"number"=>"1120", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1120 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.886743, "lng"=>-77.095041}, "accuracy"=>1, "accuracy_type"=>"range_interpolation", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1120", "predirectional"=>"N", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"N Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22201", "country"=>"US"}, "formatted_address"=>"1120 N Highland St, Arlington, VA 22201", "location"=>{"lat"=>38.886743, "lng"=>-77.09474}, "accuracy"=>0.9, "accuracy_type"=>"range_interpolation", "source"=>"TIGER/Line® dataset from the US Census Bureau"}, {"address_components"=>{"number"=>"1120", "predirectional"=>"S", "street"=>"Highland", "suffix"=>"St", "formatted_street"=>"S Highland St", "city"=>"Arlington", "county"=>"Arlington County", "state"=>"VA", "zip"=>"22204", "country"=>"US"}, "formatted_address"=>"1120 S Highland St, Arlington, VA 22204", "location"=>{"lat"=>38.860865, "lng"=>-77.089447}, "accuracy"=>0.8, "accuracy_type"=>"rooftop", "source"=>"Arlington"}]}}

    results["results"].length # => 1
    results_two["results"].length # => 3

In this example, you can see that by limiting the results to 1, we only receive the first element of the returned array. When we limit the results_two to 3 in the second example, we receive the first three elements in the array.

If you would rather not limit your results at all, you can enter nil or leave the third parameter blank.

You can also limit reverse geocode requests.

    results = geocodio.reverse(["38.9002898,-76.9990361"], [], 1)
    
    # => {"results"=>[{"address_components"=>{"number"=>"508", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"508 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900432, "lng"=>-76.999031}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}]}

    results_two = geocodio.reverse(["38.9002898,-76.9990361"], [], 4)

    # => {"results"=>[{"address_components"=>{"number"=>"508", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"508 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900432, "lng"=>-76.999031}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"510", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"510 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900429, "lng"=>-76.998965}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"506", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"506 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900437, "lng"=>-76.999099}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}, {"address_components"=>{"number"=>"504", "street"=>"H", "suffix"=>"St", "postdirectional"=>"NE", "formatted_street"=>"H St NE", "city"=>"Washington", "county"=>"District of Columbia", "state"=>"DC", "zip"=>"20002", "country"=>"US"}, "formatted_address"=>"504 H St NE, Washington, DC 20002", "location"=>{"lat"=>38.900422, "lng"=>-76.999169}, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC"}]}

    results["results"].length # => 1
    results_two["results"].length # => 4

Simple Formatting

The simple format parameter returns an alternative JSON response that is simplified and only includes the formatted address, lat, long, accuracy and source fields.

To receive a simple response, include the string "simple" as the fourth argument after any limit you have set.

Currently, the simple format only works with single geocode and reverse input. It does not support batch requests.

    ## EXAMPLE: Forward geocoding simple formatting without data appends or limit.  
    
    response = geocodio.geocode(["1109 N Highland St, Arlington, VA 22201"], [], nil, "simple")

    response # => {"address"=>"1109 N Highland St, Arlington, VA 22201", "lat"=>38.886672, "lng"=>-77.094735, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Arlington"}

    ## EXAMPLE: Reverse geocoding simple formatting with school appends and limit of 1.

    response = geocodio.reverse(["38.9002898,-76.9990361"], ["school"], 1, "simple"))

    response # => {"address"=>"508 H St NE, Washington, DC 20002", "lat"=>38.900432, "lng"=>-76.999031, "accuracy"=>1, "accuracy_type"=>"rooftop", "source"=>"Statewide DC", "fields"=>{"school_districts"=>{"unified"=>{"name"=>"District of Columbia Public Schools", "lea_code"=>"1100030", "grade_low"=>"PK", "grade_high"=>"12"}}}}

Lists API

The Geocodio Lists API allows you to upload and process a spreadsheet with addresses or coordinates. This is very similar to our Spreadsheet Uploader tool. While your spreadsheet is being processed, you can also query the status of its current progress, download the final result or delete it from your records.

You will continue to use the Geocodio##Gem class you created in the Setup portion so that you can access the Lists API methods.

Create A List

Create a new spreadsheet list job by utilizing the createList() method. To upload a spreadsheet file, pass following arguments into the method:

file: The location of the file to be geocoded.
filename: File extension is used to determine the file format. Valid formats include: CSV, TSV, XLS, XLSX.
direction: Identify whether you will be forward geocoding or reverse geocoding.
format: Provide a template for how addresses or coordinates should be read from the spreadsheet. For example:
- Full address in column A: {{A}}
- Street adresses in column A, Zip in column D: {{A}} {{D}}
- Street name in A, City in B, State in C, Zip in D: {{A}} {{B}} {{C}} {{D}}
- More examples here.
callback: Optional parameter. A valid URL that a webhook should be sent to upon completion of the spreadsheet geocoding job.

    response = geocodio.createList(File.read("sample_list_test.csv"), "sample_list_test.csv", "forward", "{{A}} {{B}} {{C}} {{D}}")

    response # => {"id"=>11599178, "file"=>{"headers"=>["address", "city", "state", "zip"], "estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}}

Check List Status

To check the current status of your List API spreadsheet upload, use the getList() method. Pass in the ID generated when you created your List to identify which list you'd like to check.

    response = geocodio.getList(11599178)

    response # => {"id"=>11599178, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T23:33:01.000000Z"}

Check All Lists

If you'd like to see all of the list jobs that you have created, use the getAllLists method. You don't need to pass anything as an argument. The endpoint is paginated, showing 15 lists at a time, ordered by most recent.

    response = geocodio.getAllLists

    response # => {"current_page"=>1, "data"=>[{"id"=>11603086, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>"https://api.geocod.io/v1.8/lists/11603086/download", "expires_at"=>"2022-12-22T22:54:23.000000Z"}, {"id"=>11603084, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>"https://api.geocod.io/v1.8/lists/11603084/download", "expires_at"=>"2022-12-22T22:49:49.000000Z"}, {"id"=>11602633, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-22T02:33:39.000000Z"}, {"id"=>11600845, "fields"=>[], "file"=>{"estimated_rows_count"=>19, "filename"=>"lat_long_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-16T17:17:40.000000Z"}, {"id"=>11600844, "fields"=>[], "file"=>{"estimated_rows_count"=>19, "filename"=>"lat_long_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-16T17:17:39.000000Z"}, {"id"=>11600843, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-16T17:17:38.000000Z"}, {"id"=>11599180, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T23:34:12.000000Z"}, {"id"=>11599179, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T23:33:47.000000Z"}, {"id"=>11599178, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T23:33:01.000000Z"}, {"id"=>11599053, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T20:03:41.000000Z"}, {"id"=>11599051, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T20:03:19.000000Z"}, {"id"=>11599050, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T20:03:18.000000Z"}, {"id"=>11598977, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T17:29:55.000000Z"}, {"id"=>11598976, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T17:29:52.000000Z"}, {"id"=>11598973, "fields"=>[], "file"=>{"estimated_rows_count"=>24, "filename"=>"sample_list_test.csv"}, "status"=>{"state"=>"COMPLETED", "progress"=>100, "message"=>"Completed", "time_left_description"=>nil, "time_left_seconds"=>nil}, "download_url"=>nil, "expires_at"=>"2022-12-10T17:29:14.000000Z"}], "first_page_url"=>"https://api.geocod.io/v1.8/lists?page=1", "from"=>1, "next_page_url"=>"https://api.geocod.io/v1.8/lists?page=2", "path"=>"https://api.geocod.io/v1.8/lists", "per_page"=>15, "prev_page_url"=>nil, "to"=>15}

Download A List

Download a spreadsheet file by using the downloadList() method. Pass in the ID you received during list creation to identify the list you would like to download. If the spreadsheet is finished processing, you will be redirected to a link that will automatically download the file.

    response = geocodio.downloadList(id)

    If the file is finished processing:

    response # => [address,city,state,zip,Latitude,Longitude,"Accuracy Score","Accuracy Type",Number,Street,"Unit Type","Unit Number",City,State,County,Zip,Country,Source], ["660 Pennsylvania Ave SE",Washington,DC,20003,38.885172,-76.996565,1,rooftop,660,"Pennsylvania Ave SE",,,Washington,DC,"District of Columbia",20003,US,Statewide],["1718 14th St NW",Washington,DC,20009,38.913274,-77.032266,1,rooftop,1718,"14th St NW",,,Washington,DC,"District of Columbia",20009,US,Statewide], ["1309 5th St NE",,,20002,38.908724,-76.997653,0.9,rooftop,1309,"5th St NE",,,Washington,DC,"District of Columbia",20002,US,Statewide], ["2150 P St NW",,,20037,38.90948,-77.048527,1,rooftop,2150,"P St NW",,,Washington,DC,"District of Columbia",20037,US,Statewide],["201 F Street NE",,,20002,38.897139,-77.003286,0.9,rooftop,201,"F St NE",,,Washington,DC,"District of Columbia",20002,US,Statewide],["1001 2nd St SE",,,20003,38.877737,-77.003695,1,rooftop,1001,"2nd St SE",,,Washington,DC,"District of Columbia",20003,US,Statewide],["1645 Wisconsin Avenue NW",Washington,DC,20007,38.911626,-77.065281,1,rooftop,1645,"Wisconsin Ave NW",,,Washington,DC,"District of Columbia",20007,US,Statewide],["820 East Baltimore Street",Baltimore,MD,21202,39.290427,-76.60485,1,rooftop,820,"E Baltimore St",,,Baltimore,MD,"Baltimore City",21202,US,"City of Baltimore"],["800 F St NW",Washington,DC,20001,38.896987,-77.023286,1,rooftop,800,"F St NW",,,Washington,DC,"District of Columbia",20004,US,Statewide],["700 Constitution Avenue NW",Washington,DC,20565,38.892228,-77.0219,0.9,range_interpolation,700,"Constitution Ave NW",,,Washington,DC,"District of Columbia",20002,US,"TIGER/Line® dataset from the US Census Bureau"],["1123 Pennsylvania Ave SE",Washington,DC,20003,38.882097,-76.990714,1,rooftop,1123,"Pennsylvania Ave SE",,,Washington,DC,"District of Columbia",20003,US,Statewide],["621 Pennsylvania Ave SE",Washington,DC,20003,38.884906,-76.997682,1,rooftop,621,"Pennsylvania Ave SE",,,Washington,DC,"District of Columbia",20003,US,Statewide],["1702 G Street NW",Washington,DC,20006,38.89816,-77.039982,1,rooftop,1702,"G St NW",,,Washington,DC,"District of Columbia",20006,US,Statewide],["701 8th St SE",Washington,DC,20003,38.881115,-76.995245,1,rooftop,701,"8th St SE",,,Washington,DC,"District of Columbia",20003,US,Statewide],["12187 Darnestown Rd",Gaithersburg,MD,20878,39.118169,-77.251699,1,rooftop,12187,"Darnestown Rd",,,Gaithersburg,MD,"Montgomery County",20878,US,Montgomery],["4961 Elm Street",Bethesda,MD,,38.982196,-77.098161,1,rooftop,4961,"Elm St",,,Bethesda,MD,"Montgomery County",20814,US,Montgomery],["3064 Mount Pleasant St NW",Washington,DC,,38.92846,-77.037509,1,rooftop,3064,"Mt Pleasant St NW",,,Washington,DC,"District of Columbia",20009,US,Statewide],["1052 Thomas Jefferson Street NW",Washington,DC,,38.903887,-77.060437,1,rooftop,1052,"Thomas Jefferson St NW",,,Washington,DC,"District of Columbia",20007,US,Statewide],["475 H St NW",Washington,DC,,38.900078,-77.018645,1,rooftop,475,"H St NW",,,Washington,DC,"District of Columbia",20001,US,Statewide],["1301 U St NW",Washington,DC,,38.917294,-77.03052,1,rooftop,1301,"U St NW",,,Washington,DC,"District of Columbia",20009,US,Statewide],["1726 20th Street, NW",Washington,DC,,38.913694,-77.045095,1,rooftop,1726,"20th St NW",,,Washington,DC,"District of Columbia",20009,US,Statewide],["1916 I Street, NW",Washington,DC,,38.90115,-77.044172,1,rooftop,1916,"I St NW",,,Washington,DC,"District of Columbia",20006,US,Statewide],["107 Church St NE",Vienna,VA,,38.902565,-77.265693,1,rooftop,107,"Church St NE",,,Vienna,VA,"Fairfax County",22180,US,Fairfax],["4817 Bethesda Ave",Bethesda,MD,20814,38.981067,-77.096506,1,rooftop,4817,"Bethesda Ave",,,Bethesda,MD,"Montgomery County",20814,US,Montgomery]

    If the file is not finished processing: 

    response # =>  {
        "message": "List is still processing",
        "success": false
    }

Delete A List

Delete an existing list by utilizing the deleteList() method. If the job is complete, this will delete both the list data and the spreadsheet data contained within. The spreadsheet data will be automatically deleted in 72 hours if it is not manually deleted using deleteList().

You can also use this method to cancel a current list job while it is still processing. Geocodio Unlimited customers can cancel a spreadsheet at any time, while Pay-As-You-Go customers can only do so if the spreadsheet job was started recently.

To use deleteList(), pass in the ID of the list you would like to delete.

    response = geocodio.deleteList(11599181)

    response # => {"success"=>true}

Distance Calculations

The Distance API allows you to calculate distances from a single origin to multiple destinations, or compute full distance matrices.

Coordinate Formats with Custom IDs

You can add custom identifiers to coordinates using various formats. The ID will be returned in the response, making it easy to match results back to your data:

# String format with ID
"37.7749,-122.4194,warehouse_1"

# Array format with ID
[37.7749, -122.4194, "warehouse_1"]

# Hash format with ID
{ lat: 37.7749, lng: -122.4194, id: "warehouse_1" }

Distance Mode and Units

The SDK supports different distance calculation modes and units:

# Available modes
:straightline  # Default - great-circle (as the crow flies)
:driving       # Road network routing with duration
:haversine     # Alias for straightline (backward compatibility)

# Available units
:miles         # Default
:kilometers

Note: The default mode is :straightline (great-circle distance). Use :driving if you need road network routing with duration estimates.

Single Origin to Multiple Destinations

Calculate distances from one origin to multiple destinations:

# Basic usage with string coordinates
response = geocodio.distance(
  "38.8977,-77.0365,white_house",
  ["38.9072,-77.0369,capitol", "38.8895,-77.0353,monument"]
)

response["origin"]["id"]  # => "white_house"
response["destinations"][0]["distance_miles"]  # => 0.7
response["destinations"][0]["id"]  # => "capitol"

# With driving mode (includes duration)
response = geocodio.distance(
  "38.8977,-77.0365",
  ["38.9072,-77.0369"],
  mode: :driving
)

response["destinations"][0]["duration_seconds"]  # => 180

# With filtering and sorting options
response = geocodio.distance(
  "38.8977,-77.0365,warehouse",
  [
    "38.9072,-77.0369,store_1",
    "39.2904,-76.6122,store_2",
    "39.9526,-75.1652,store_3"
  ],
  mode: :driving,
  units: :kilometers,
  max_results: 2,
  max_distance: 100.0,
  order_by: :distance,
  sort: :asc
)

# Using array format for coordinates
response = geocodio.distance(
  [38.8977, -77.0365, "headquarters"],
  [[38.9072, -77.0369, "branch_1"]]
)

# Using hash format for coordinates
response = geocodio.distance(
  { lat: 38.8977, lng: -77.0365, id: "hq" },
  [{ lat: 38.9072, lng: -77.0369, id: "branch" }]
)

Distance Matrix (Multiple Origins to Multiple Destinations)

Calculate full distance matrix from multiple origins to multiple destinations:

origins = [
  "38.8977,-77.0365,warehouse_dc",
  "39.2904,-76.6122,warehouse_baltimore"
]
destinations = [
  "38.9072,-77.0369,customer_1",
  "39.9526,-75.1652,customer_2"
]

response = geocodio.distanceMatrix(origins, destinations)

response["results"][0]["origin"]["id"]  # => "warehouse_dc"
response["results"][0]["destinations"][0]["distance_miles"]  # => 0.7

# With driving mode
response = geocodio.distanceMatrix(
  origins,
  destinations,
  mode: :driving,
  units: :kilometers
)

# With filtering options
response = geocodio.distanceMatrix(
  origins,
  destinations,
  max_results: 2,
  max_distance: 50.0,
  min_distance: 1.0,
  order_by: :distance,
  sort: :asc
)

Add Distance to Geocoding Requests

You can add distance calculations to existing geocode or reverse geocode requests:

# Geocode an address and calculate distances to store locations
response = geocodio.geocode(
  ["1600 Pennsylvania Ave NW, Washington DC"],
  [],     # fields
  nil,    # limit
  nil,    # format
  destinations: [
    "38.9072,-77.0369,store_dc",
    "39.2904,-76.6122,store_baltimore"
  ],
  distance_mode: :driving,
  distance_units: :miles
)

response["results"][0]["destinations"][0]["distance_miles"]  # => distance to first destination
response["results"][0]["destinations"][0]["id"]  # => "store_dc"

# Reverse geocode with distances
response = geocodio.reverse(
  ["38.8977,-77.0365"],
  [],
  nil,
  nil,
  destinations: ["38.9072,-77.0369,capitol"],
  distance_mode: :straightline
)

response["results"][0]["destinations"]  # => array of destinations with distances

Async Distance Matrix Jobs

For large distance matrix calculations, use async jobs that process in the background:

# Create a new distance matrix job
job = geocodio.createDistanceMatrixJob(
  "My Distance Calculation",
  ["38.8977,-77.0365,origin_1", "38.9072,-77.0369,origin_2"],
  ["38.8895,-77.0353,dest_1", "39.2904,-76.6122,dest_2"],
  mode: :driving,
  units: :miles,
  callback_url: "https://example.com/webhook"  # Optional
)

job["id"]  # => Job identifier

# Or use list IDs from previously uploaded lists
job = geocodio.createDistanceMatrixJob(
  "Distance from Lists",
  12345,    # List ID for origins
  67890,    # List ID for destinations
  mode: :straightline
)

# Check job status
status = geocodio.distanceMatrixJobStatus(job["id"])

status["data"]["status"]  # => "COMPLETED", "PROCESSING", or "FAILED"
status["data"]["progress"]  # => 0-100

# List all jobs (paginated)
jobs = geocodio.distanceMatrixJobs
jobs = geocodio.distanceMatrixJobs(2)  # Page 2

# Get job results as parsed hash
results = geocodio.getDistanceMatrixJobResults(job["id"])

results["results"][0]["origin"]["id"]  # => "origin_1"
results["results"][0]["destinations"]  # => array of destinations with distances

# Download results to file
geocodio.downloadDistanceMatrixJob(job["id"], "/path/to/results.json")

# Delete a job
geocodio.deleteDistanceMatrixJob(job["id"])

Distance Filtering Options

All distance methods support the following filtering options:

Option	Type	Description
`mode`	Symbol	`:straightline` (default), `:driving`, or `:haversine`
`units`	Symbol	`:miles` (default), `:kilometers`, or `:km`
`max_results`	Integer	Limit number of results
`max_distance`	Float	Filter by maximum distance
`min_distance`	Float	Filter by minimum distance
`max_duration`	Integer	Filter by max duration in seconds (driving mode only)
`min_duration`	Integer	Filter by min duration in seconds (driving mode only)
`order_by`	Symbol	`:distance` (default) or `:duration`
`sort`	Symbol	`:asc` (default) or `:desc`

Testing

To run tests, be sure to create a .env file that export your Geocodio API Key within a variable of API_KEY.

    export API_KEY=<YOUR API KEY>

Then, run rspec.

    rspec

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The gem is available as open source under the terms of the MIT License.