geoplanet¶ ↑

A Ruby wrapper for the Yahoo! GeoPlanet APIs. It’s inspired on Mattt Thompson’s yahoo-geoplanet gem, but this version supports better usage of matrix and query parameters, uses JSON for API communication to minimize bandwidth usage, supports both short & long versions of a place, and supports multiple languages.

INSTALL:¶ ↑

gem install geoplanet

Usage¶ ↑

Searching for a Location:¶ ↑

require 'geoplanet'
GeoPlanet.appid = [Your App ID Here]

# Search for places that matches "Springfield" (the API returns 1 by default)
GeoPlanet::Place.search("Springfield")

# Search for *all* places that matches "Springfield"
GeoPlanet::Place.search("Springfield", :count => 0)

# Search for "Toronto" with focus on "Canada"
GeoPlanet::Place.search("Toronto", :focus => "ca")

# You can pass in any Matrix or Query parameters this way too
# For more details see the following URLs:
# http://developer.yahoo.com/geo/guide/resources_and_collections.html#matrix_parameters
# http://developer.yahoo.com/geo/guide/resources_and_collections.html#query_parameters

Initializing by Where On Earth ID && Associations¶ ↑

require 'geoplanet'
GeoPlanet.appid = [Your App ID Here]

a = GeoPlanet::Place.new(752067) # WoE ID for Algeciras

# Everything you get back from the API you have direct access to
# through the Place object. For example:

a.version          # "long"
a.placetype        # "Town"
a.placetype_code   # 7
a.admin1           # "Andalucia"
a.admin1_code      # "ES-AN"
a.admin1_placetype # "Autonomous Community"
a.admin2           # "Cadiz"
a.admin2_code      # ""
a.admin2_placetype # "Province"
a.latitude         # 36.127602
                   # Latitude and Longitude are values at Centroid
a.bounding_box     # [[36.109779, -5.47725], [36.164268, -5.43527]]
                   # Bounding box are SW / NE coordinates in array
a.pop_rank         # 11
                   # Code representing population size
a.area_rank        # 4
                   # Code representing the size of the place
                   # See codes at http://developer.yahoo.com/geo/geoplanet/guide/api_docs.html

# We unlock the true power of GeoPlanet with association collections
# Check out this truly amazing stuff:

# A list of other towns in the area
a.siblings

# A complete hierarchy, from country down to municipality
a.ancestors

# All descendants for a location
a.descendants(count: 0)

# Postal Codes at Algeciras
a.children(:select => "long", :type => 11)

# You can use multiple types on the same query.
# e.g. Country and Province for Algeciras
a.belongtos(:type => [12, 9])

# You can specify the language you want for the results.
a.belongtos(:type => 12, :lang => 'es_ES').first.name  # España

a = GeoPlanet::Place.new(752067, :lang => :es)
a.country  # España

# It is also possible to query for any association directly using a WOE ID, without
# create a Place object. Append a '_of' suffix to the association name to build the
# method name to execute. The first argument is the WOE ID.

GeoPlanet::Place.belongtos_of(752067, :type => [12, 9])

Debug Mode¶ ↑

If you want to look at the requests that are being executed against the Yahoo GeoPlanet API, you can enable the debug mode. It uses the standard output.

GeoPlanet.debug = true
GeoPlanet::Place.new(752067, :lang => :es)
# outputs:
# Yahoo GeoPlanet: GET http://where.yahooapis.com/v1/place/752067?appid=[your_appid]&format=json&lang=es

REQUIREMENTS:¶ ↑

To use this library, you must have a valid Yahoo! App ID. You can get one at developer.yahoo.com/wsregapp/

Additionally, geoplanet has the following gem dependencies:

rest-client >= 0.9
json >= 1.1.3

LICENSE:¶ ↑

(The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Credits¶ ↑

Carlos Paramio

carlosparamio.com

geoplanet

Runtime