{"id":16431987,"url":"https://github.com/davidcelis/geocodio","last_synced_at":"2025-09-13T07:14:18.886Z","repository":{"id":13431007,"uuid":"16119902","full_name":"davidcelis/geocodio","owner":"davidcelis","description":"A ruby client for the http://geocod.io/ API. Geocode with ease.","archived":false,"fork":false,"pushed_at":"2022-07-12T20:32:05.000Z","size":76,"stargazers_count":20,"open_issues_count":5,"forks_count":24,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-01T12:29:41.939Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://geocod.io/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidcelis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-01-21T21:41:43.000Z","updated_at":"2023-03-14T23:39:26.000Z","dependencies_parsed_at":"2022-09-18T18:15:01.466Z","dependency_job_id":null,"html_url":"https://github.com/davidcelis/geocodio","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidcelis%2Fgeocodio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidcelis%2Fgeocodio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidcelis%2Fgeocodio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidcelis%2Fgeocodio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidcelis","download_url":"https://codeload.github.com/davidcelis/geocodio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221666413,"owners_count":16860415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T08:35:20.838Z","updated_at":"2024-10-27T11:00:01.955Z","avatar_url":"https://github.com/davidcelis.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geocodio [![Build Status](https://travis-ci.org/davidcelis/geocodio.png?branch=master)](https://travis-ci.org/davidcelis/geocodio) [![Coverage Status](https://coveralls.io/repos/davidcelis/geocodio/badge.png)](https://coveralls.io/r/davidcelis/geocodio) [![Code Climate](https://codeclimate.com/github/davidcelis/geocodio.png)](https://codeclimate.com/github/davidcelis/geocodio)\n\nGeocodio is a lightweight Ruby wrapper around the [geocod.io][geocod.io] API.\n\n## Installation\n\nIn your Gemfile:\n\n```ruby\ngem 'geocodio'\n```\n\n## Usage\n\nThe point of entry to geocod.io's API is the `Geocodio::Client` class. Initialize\none by passing your API key or allowing the initializer to automatically use\nthe `GEOCODIO_API_KEY` environment variable:\n\n```ruby\ngeocodio = Geocodio::Client.new('0123456789abcdef')\n\n# Or, if you've set GEOCODIO_API_KEY in your environment:\ngeocodio = Geocodio::Client.new\n```\n\n### Geocoding\n\nThe `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:\n\n```ruby\nresults = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014'])\n# =\u003e #\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"1 Infinite Loop, Cupertino, CA 95014\", @addresses=[...]\u003e\n```\n\nAddressSets are enumerable, so you can iterate over each result and perform operations on the addresses:\n\n```ruby\nresults.each { |address| puts address }\n```\n\nIf you just want the most accurate result, use the `#best` convenience method:\n\n```ruby\naddress = results.best\n# =\u003e #\u003cGeocodio::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\"\u003e\n\nputs address\n# =\u003e 1 Infinite Loop, Cupertino CA, 95014\n\nputs address.latitude # or address.lat\n# =\u003e 37.331669\n\nputs address.longitude # or address.lng\n# =\u003e -122.03074\n```\n\nTo perform a batch geocoding operation as mentioned earlier, simply add more addresses to the passed array:\n\n```ruby\nresult_sets = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014', '54 West Colorado Boulevard, Pasadena, CA 91105'])\n# =\u003e [#\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"1 Infinite Loop, Cupertino, CA 95014\", @addresses=[...]\u003e, #\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"54 West Colorado Boulevard, Pasadena, CA 91105\", @addresses=[...]\u003e]\n\ncupertino = result_sets.first.best\n# =\u003e #\u003cGeocodio::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\"\u003e\n```\n\n### Reverse Geocoding\n\nThe 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:\n\n```ruby\naddresses = geocodio.reverse_geocode(['37.331669,-122.03074'])\n# =\u003e #\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"1 Infinite Loop, Cupertino, CA 95014\", @addresses=[...]\u003e\n\naddress_sets = geocodio.reverse_geocode(['37.331669,-122.03074', '34.145760590909,-118.15204363636'])\n# =\u003e [#\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"1 Infinite Loop, Cupertino, CA 95014\", @addresses=[...]\u003e, #\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"54 West Colorado Boulevard, Pasadena, CA 91105\", @addresses=[...]\u003e]\n```\n\nCoordinate pairs can also be specified as hashes:\n\n```ruby\naddress_sets = geocodio.reverse_geocode([{ lat: 37.331669, lng: -122.03074 }, { latitude: 34.145760590909, longitude: -118.15204363636 }])\n# =\u003e [#\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"1 Infinite Loop, Cupertino, CA 95014\", @addresses=[...]\u003e, #\u003cGeocodio::AddressSet:0x007fdf23a07f80 @query=\"54 West Colorado Boulevard, Pasadena, CA 91105\", @addresses=[...]\u003e]\n```\n\n### Parsing\n\n```ruby\naddress = geocodio.parse('1 Infinite Loop, Cupertino, CA 95014')\n# =\u003e #\u003cGeocodio::Address:0x007fa3c15f41c0 @number=\"1\", @street=\"Infinite\", @suffix=\"Loop\", @city=\"Cupertino\", @state=\"CA\", @zip=\"95014\", @accuracy=nil, @formatted_address=\"1 Infinite Loop, Cupertino CA, 95014\"\u003e\n```\n\nNote that this endpoint performs no geocoding; it merely formats a single provided address according to geocod.io's standards.\n\n### Additional fields\n\nGeocodio has added support for retrieving [additional fields][fields] when geocoding or reverse geocoding. To request these fields, pass an options hash to either `#geocode` or `#reverse_geocode`. Possible fields include `cd` or `cd113`, `stateleg`, `school`, and `timezone`:\n\n```ruby\naddress = geocodio.geocode(['54 West Colorado Boulevard Pasadena CA 91105'], fields: %w[cd stateleg school timezone]).best\n\naddress.congressional_districts\n# =\u003e #\u003cGeocodio::CongressionalDistrict:0x007fa3c15f41c0 @name=\"Congressional District 27\" @district_number=27 @congress_number=113 @congress_years=2013..2015\u003e\n\naddress.house_district\n# =\u003e #\u003cGeocodio::StateLegislativeDistrict:0x007fa3c15f41c0 @name=\"Assembly District 41\" @district_number=41\u003e\n\naddress.senate_district\n# =\u003e #\u003cGeocodio::StateLegislativeDistrict:0x007fa3c15f41c0 @name=\"State Senate District 25\" @district_number=25\u003e\n\naddress.unified_school_district # or .elementary_school_district and .secondary_school_district if not unified\n# =\u003e #\u003cGeocodio::SchoolDistrict:0x007fa3c15f41c0 @name=\"Pasadena Unified School District\" @lea_code=\"29940\" @grade_low=\"KG\" @grade_high=\"12\"\u003e\n\naddress.timezone\n# =\u003e #\u003cGeocodio::Timezone:0x007fa3c15f41c0 @name=\"PST\" @utc_offset=-8 @observes_dst=true\u003e\naddress.timezone.observes_dst?\n# =\u003e true\n```\n\n## Contributing\n\n1. Fork it ( http://github.com/davidcelis/geocodio/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n[geocod.io]: http://geocod.io/\n[fields]: http://geocod.io/docs/?ruby#toc_17\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidcelis%2Fgeocodio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidcelis%2Fgeocodio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidcelis%2Fgeocodio/lists"}