gem install ym4r

Relation between the YM4R gem and the YM4R/GM plugin for Rails

They are completely independent from each other.

With the plugin, you don’t need the YM4R gem anymore, unless you want to use the Yahoo! Maps Building Block API’s, the tilers or the Google Maps geocoding REST API. All of these functionalities are detailed in the current document.

Conversely, the YM4R gem does not need the plugin to work.

=== Operations
Google Maps Geocoding API

Here is an example of request:

require 'ym4r/google_maps/geocoding'
include Ym4r::GoogleMaps
results = Geocoding::get("Rue Clovis Paris")

results is an array of Geocoding::Placemark objects, with 2 additional attributes: status and name. You should check if status equals Geocoding::GEO_SUCCESS to know if the request has been successful. You can access the various data elements like this:

if results.status == Geocoding::GEO_SUCCESS
        a = results[0].address
        b = results[0].latlon
end

Yahoo Maps Building Block API

Building Block API’s (Geocoding, Map Image, Traffic and Local Search) are supported. You have to pass to the get method of the module a hash whose keys are a rubyfied version of the request parameters detailed in the documentation for these API’s. You get back a ruby object, with accessors that let you get the returned data in a easy way. You get an exception if not all the parameters have been passed, if the connection to the service could not be made or if the parameters you have passed are of the incorrect value.

To know what parameters to pass to the get methods and what results you should expect, you should consult the documentation for the building block API’s on Yahoo!’s website : developer.yahoo.com/maps/index.html#mapsBuildingBlocks .

Here are some examples and notes about using the different Building Block API’s.
Geocoding

Here is an example of request:

require 'ym4r/yahoo_maps/building_block'
include Ym4r::YahooMaps::BuildingBlock
results = Geocoding::get(:street => "1 Infinite Loop",
                          :city => "Cupertino",
                          :state => "CA",
                          :zip => "95014")

results is an array of Geocoding::Result objects. The API can return up to 50 results for one request. You can access the data in the result with attributes which are rubyfied versions of the XML elements forming the answer from the service: See the Yahoo! Geocoding documentation to know what these are and their meanings.
Map Image

Here is an example of request:

require 'ym4r/yahoo_maps/building_block'
include Ym4r::YahooMaps::BuildingBlock
result = MapImage::get(:street => "1 Infinite Loop",
                       :city => "Cupertino",
                       :state => "CA",
                       :zip => "95014",
                       :image_type => "png")

result is a MapImage::Result object contains the URL for the requested image. You can download this image to a file by calling download_to and passing a path.
Traffic

Here is an example of request:

require 'ym4r/yahoo_maps/building_block'
include Ym4r::YahooMaps::BuildingBlock
results = Traffic::get(:street => "1 Infinite Loop",
                       :city => "Cupertino",
                       :state => "CA",
                       :zip => "95014",
                       :include_map => true)

results is a Traffic::ResultSet object (subclass of Array), containing Traffic::Result objects, each containing information about one traffic incident.
Local Search

Here is an example of request:

require 'ym4r/yahoo_maps/building_block'
include Ym4r::YahooMaps::BuildingBlock
results = LocalSearch::get(:street => "1 Infinite Loop",
                           :city => "Cupertino",
                           :state => "CA",
                           :zip => "95014",
                           :query => "chinese")

results is a LocalSearch::ResultSet object (subclass of Array), containing LocalSearch::Result objects, each containing information about one hit on the Yahoo! local search.