carlosparamio-geoplanet

= 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.

== 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)

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

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

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 http://developer.yahoo.com/wsregapp/

Additionally, geoplanet has the following gem dependencies:

• rest-client >= 0.9
• json >= 1.1.3

Please note that if you have ActiveSupport::JSON defined (either by manually having loaded it or when you use geoplanet within a Rails application) the json dependency will be ignored and geoplanet uses ActiveSupport::JSON instead.

== INSTALL:

• gem install carlosparamio-geoplanet --source http://gems.github.com

== LICENSE:

(The MIT License)

Copyright (c) 2009 Carlos Paramio

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.

== CONTRIBUTORS:

Nielsomat http://github.com/Nielsomat : Usage of ActiveSupport::JSON when available