This is YM4R 0.5.2. YM4R has features to ease the use of the Google Maps Geocoding API and the Yahoo! Maps building block API’s from Ruby. If you are looking to use the main Google Maps API from your Rails application, you should use the YM4R/GM plugin for Rails (thepochisuperstarmegashow.com/projects/#ym4r).
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.
Just type under a command line:
gem install ym4r
And the last version will be automatically downloaded and installed.
It can be useful if you cannot install global gems on the machine where you are going to deploy your application (for example on a shared host).
You first need to unpack the gem. To do this, if the gem is installed on your local machine, type:
gem unpack ym4r
You can also directly untar the gem (after having downloaded it first) if you prefer:
tar xf ym4r-0.3.2.gem
then:
tar xzf data.tar.gz
Then copy the content of the lib directory of the gem into the lib
directory of your rails application: You should have in
RAILS_ROOT/lib
the ym4.rb
file and the
ym4r
directory (plus a tasks folder; which was already there
before). Contrary to what is done for a plugin, you will still need to
require and include in your application the files and modules you are
interested in.
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
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.
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.
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.
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.
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.
Removed the tilers. They are now in a separately downloadable package.
Changed the Yahoo App Id
Add more tests
This software is not endorsed in any way by Yahoo! or Google.
YM4R is released under the MIT license.
Any questions, enhancement proposals, bug notifications or corrections can be sent to guilhem.vellut+ym4r@gmail.com.