Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/davidcelis/geocodio
A ruby client for the http://geocod.io/ API. Geocode with ease.
https://github.com/davidcelis/geocodio
Last synced: about 2 months ago
JSON representation
A ruby client for the http://geocod.io/ API. Geocode with ease.
- Host: GitHub
- URL: https://github.com/davidcelis/geocodio
- Owner: davidcelis
- License: mit
- Created: 2014-01-21T21:41:43.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2022-07-12T20:32:05.000Z (over 2 years ago)
- Last Synced: 2024-05-01T12:29:41.939Z (8 months ago)
- Language: Ruby
- Homepage: http://geocod.io/
- Size: 74.2 KB
- Stars: 20
- Watchers: 2
- Forks: 24
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Geocodio [](https://travis-ci.org/davidcelis/geocodio) [](https://coveralls.io/r/davidcelis/geocodio) [](https://codeclimate.com/github/davidcelis/geocodio)
Geocodio is a lightweight Ruby wrapper around the [geocod.io][geocod.io] API.
## Installation
In your Gemfile:
```ruby
gem 'geocodio'
```
## 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:
```ruby
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:
```ruby
results = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014'])
# => #
```
AddressSets are enumerable, so you can iterate over each result and perform operations on the addresses:
```ruby
results.each { |address| puts address }
```
If you just want the most accurate result, use the `#best` convenience method:
```ruby
address = results.best
# => #
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:
```ruby
result_sets = geocodio.geocode(['1 Infinite Loop, Cupertino, CA 95014', '54 West Colorado Boulevard, Pasadena, CA 91105'])
# => [#, #]
cupertino = result_sets.first.best
# => #
```
### 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:
```ruby
addresses = geocodio.reverse_geocode(['37.331669,-122.03074'])
# => #
address_sets = geocodio.reverse_geocode(['37.331669,-122.03074', '34.145760590909,-118.15204363636'])
# => [#, #]
```
Coordinate pairs can also be specified as hashes:
```ruby
address_sets = geocodio.reverse_geocode([{ lat: 37.331669, lng: -122.03074 }, { latitude: 34.145760590909, longitude: -118.15204363636 }])
# => [#, #]
```
### Parsing
```ruby
address = geocodio.parse('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][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`:
```ruby
address = geocodio.geocode(['54 West Colorado Boulevard Pasadena CA 91105'], fields: %w[cd stateleg school timezone]).best
address.congressional_districts
# => #
address.house_district
# => #
address.senate_district
# => #
address.unified_school_district # or .elementary_school_district and .secondary_school_district if not unified
# => #
address.timezone
# => #
address.timezone.observes_dst?
# => true
```
## Contributing
1. Fork it ( http://github.com/davidcelis/geocodio/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
[geocod.io]: http://geocod.io/
[fields]: http://geocod.io/docs/?ruby#toc_17