Methods

Geocode function

Gmaps4rails.geocode(address) retrieves an Array of Hash of potential coordinates.

Each hash is made up: latitude, longitude and matched_adress retrieved by Google.

Here is an example:

Gmaps4rails.geocode("Caroline")
=> [
    {:lat=>-9.9599095, :lng=>-150.2052861, :matched_address=>"Millennium Island, French Polynesia"}, 
    {:lat=>44.72083, :lng=>-88.89139, :matched_address=>"Caroline, WI, USA"}, 
    {:lat=>42.37833, :lng=>-76.29583, :matched_address=>"Caroline, NY 14817, USA"}, 
    #many other results...
   ]

It could raise two kinds of exception:

1. GeocodeStatus Basically, Google can't find the address provided: raise Gmaps4rails::GeocodeStatus, "The adress you passed seems invalid, status was: #{parse["status"]}. Request was: #{request}"

2. GeocodeNetStatus No Http Success.

   raise Gmaps4rails::GeocodeNetStatus, "The request sent to google was invalid (not http success): #{request}.
   Response was: #{resp}"
   

to_gmaps4rails

Could follow an array of objects or a single object.

It creates the json that would be passed to google, in accordance with the details you gave.

Destination function

Details here: http://code.google.com/apis/maps/documentation/directions/#RequestParameters

Gmaps4rails.destination(start_end, options={}, output="pretty")

• start_end is a Hash: { "from" => "", "to" => "" }

• options can contain the following data:

  • mode: "DRIVING", "WALKING" or "BICYCLING", default is "DRIVING"

  • waypoints: Array of strings containing your waypoints ["here", "there"], default is empty

  • avoid: Array which could contain at most ["tolls", "highways"], default is empty

  • units: String "METRIC" or "IMPERIAL", default is "METRIC"

  • region: String

  • language: String, default is "en"

• output determines the way you want the result:

  • pretty: renders the result from Google with the polylines separated in a ready for use variable

  • clean: renders the result from Google without the encoded polylines

  • raw: renders the raw result from Google

Destination results

Result is an Array of legs (according to Google: "Each element in the legs array specifies a single leg of the journey from the origin to the destination in the calculated route.").

One leg contains several steps: "A step is the most atomic unit of a direction's route, containing a single step describing a specific, single instruction on the journey."

 [
  #leg1
  {
   "duration"  => { "text" => string, "value" => float },
   "distance"  => { "text" => string, "value" => float },
   "steps"     => Array of Hashes,
   "polylines" => json_containing_encoded_polylines        #depending on the value of 'output' you set
  },
  #leg2
  {
   "duration"  => { "text" => string, "value" => float },
   "distance"  => { "text" => string, "value" => float },
   "steps"     => Array of Hashes,
   "polylines" => json_containing_encoded_polylines
  }
  ...
 ]

Example:

Gmaps4rails.destination(
  {"from" => "Toulon, france", "to" => "marseille, france"}, 
  {
    "language"  => "fr", 
    "waypoints" => ["Cassis,france"],
    "mode"      => "DRIVING",
    "avoid"     => ["tolls", "highways"],
    "language"  => "fr"
  }, 
  "pretty"
  )

Errors

It could raise two kinds of exception:

1. DirectionStatus Basically, Google can't find any path from the data you provided: raise Gmaps4rails::GeocodeStatus, "The query you passed seems invalid, status was: #{parse["status"]}. Request was: #{request}"

2. DirectionNetStatus No Http Success.

   raise Gmaps4rails::DirectionNetStatus, "The request sent to google was invalid (not http success): #{request}.
   Response was: #{resp}"