google_maps

v0.1.0

google_maps v0.1.0 GoogleMaps

Provides various map-related functionality.

Unless otherwise noted, all the functions take the required Google parameters as its own parameters, and all optional ones in an options keyword list.

Summary

Types

address()

An address that will be geocoded and converted to latitude/longitude coordinate

body()
coordinate()

A latitude/longitude pair in tuple or comma-separated string format

error()
headers()
latitude()
longitude()
mode()
place_id()

A tagged tuple with an ID of a known place

status()
waypoint()

A specific point, which can be an address, a latitude/longitude coord or a place id tupple

Functions

delete(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url

delete!(url, headers \\ [], options \\ [])

Issues a DELETE request to the given url, raising an exception in case of failure

directions(origin, destination, options \\ [])

Retrives the directions from one point to the other

get(endpoint, params)
get(url, headers \\ [], options \\ [])

Issues a GET request to the given url

get!(url, headers \\ [], options \\ [])

Issues a GET request to the given url, raising an exception in case of failure

head(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url

head!(url, headers \\ [], options \\ [])

Issues a HEAD request to the given url, raising an exception in case of failure

options(url, headers \\ [], options \\ [])

Issues an OPTIONS request to the given url

options!(url, headers \\ [], options \\ [])

Issues a OPTIONS request to the given url, raising an exception in case of failure

patch(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url

patch!(url, body, headers \\ [], options \\ [])

Issues a PATCH request to the given url, raising an exception in case of failure

post(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url

post!(url, body, headers \\ [], options \\ [])

Issues a POST request to the given url, raising an exception in case of failure

process_response_body(body)
process_url(url)
put(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url

put!(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url, raising an exception in case of failure

request(method, url, body \\ "", headers \\ [], options \\ [])

Issues an HTTP request with the given method to the given url

request!(method, url, body \\ "", headers \\ [], options \\ [])

Issues an HTTP request with the given method to the given url, raising an exception in case of failure

start()

Starts HTTPoison and its dependencies

stream_next(async_response)

Requests the next message to be streamed for a given HTTPoison.AsyncResponse

Types

address() 
address :: String.t

An address that will be geocoded and converted to latitude/longitude coordinate.

body() 
body :: binary | {:form, [{atom, any}]} | {:file, binary}
coordinate() 
coordinate :: {latitude, longitude} | String.t

A latitude/longitude pair in tuple or comma-separated string format.

headers() 
headers ::
  [{binary, binary}] |
  %{optional(binary) => binary}
latitude() 
latitude :: number
longitude() 
longitude :: number
mode() 
mode :: String.t
place_id() 
place_id :: {:place_id, String.t}

A tagged tuple with an ID of a known place.

status() 
status :: String.t
waypoint() 
waypoint :: address | coordinate | place_id

A specific point, which can be an address, a latitude/longitude coord or a place id tupple.

Functions

delete(url, headers \\ [], options \\ []) 
delete(binary, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a DELETE request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

delete!(url, headers \\ [], options \\ []) 
delete!(binary, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a DELETE request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

directions(origin, destination, options \\ []) 
directions(waypoint, waypoint, keyword) ::
  {:ok, map} |
  {:error, error}

Retrives the directions from one point to the other.

Args:

  • origin — The address, textual latitude/longitude value, or place ID from which you wish to calculate directions. If you pass an address, the Directions service geocodes the string and converts it to a latitude/longitude coordinate to calculate directions. This coordinate may be different from that returned by the Google Maps Geocoding API, for example a building entrance rather than its center. Place IDs must be prefixed with place_id:. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID. You can retrieve place IDs from the Google Maps Geocoding API and the Google Places API (including Place Autocomplete).
  • destination — The address, textual latitude/longitude value, or place ID to which you wish to calculate directions. The options for the destination parameter are the same as for the origin parameter, described above.

Options:

  • mode (defaults to driving) — Specifies the mode of transport to use when calculating directions. Valid values and other request details are specified in Travel Modes section.
  • waypoints— Specifies an array of waypoints. Waypoints alter a route by routing it through the specified location(s). A waypoint is specified as a latitude/longitude coordinate, an encoded polyline, a place ID, or an address which will be geocoded. Encoded polylines must be prefixed with enc: and followed by a colon (:). Place IDs must be prefixed with place_id:. The place ID may only be specified if the request includes an API key or a Google Maps APIs Premium Plan client ID. Waypoints are only supported for driving, walking and bicycling directions.
  • alternatives — If set to true, specifies that the Directions service may provide more than one route alternative in the response. Note that providing route alternatives may increase the response time from the server.

  • avoid — Indicates that the calculated route(s) should avoid the indicated features. Supports the following arguments:

    • tolls indicates that the calculated route should avoid toll roads/bridges.
    • highways indicates that the calculated route should avoid highways.
    • ferries indicates that the calculated route should avoid ferries.
    • indoor indicates that the calculated route should avoid indoor steps for walking and transit directions. Only requests that include an API key or a Google Maps APIs Premium Plan client ID will receive indoor steps by default.

  • language — The language in which to return results.

    • See the list of supported languages.
    • If language is not supplied, the API attempts to use the preferred language as specified in the language config, or the native language of the domain from which request is sent.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.
  • units — Specifies the unit system to use displaying results.
  • region — Specifies the region code, specified as a ccTLD (“top-level domain”) two-character value.
  • arrival_time — Specifies the desired time of arrival for transit directions, in seconds since midnight, January 1, 1970 UTC. You can specify either departure_time or arrival_time, but not both. Note that arrival_time must be specified as an integer.

  • departure_time — Specifies the desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC. Alternatively, you can specify a value of now, which sets the departure time to the current time (correct to the nearest second). The departure time may be specified in two cases:

    • For requests where the travel mode is transit: You can optionally specify one of departure_time or arrival_time. If neither time is specified, the departure_time defaults to now (that is, the departure time defaults to the current time).
    • For requests where the travel mode is driving: You can specify the departure_time to receive a route and trip duration (response field: duration_in_traffic) that take traffic conditions into account. This option is only available if the request contains a valid API key, or a valid Google Maps APIs Premium Plan client ID and signature. The departure_time must be set to the current time or some time in the future. It cannot be in the past.

  • traffic_model (defaults to best_guess) — Specifies the assumptions to use when calculating time in traffic. This setting affects the value returned in the duration_in_traffic field in the response, which contains the predicted time in traffic based on historical averages. The traffic_model parameter may only be specified for driving directions where the request includes a departure_time, and only if the request includes an API key or a Google Maps APIs Premium Plan client ID. The available values for this parameter are:

    • best_guess (default) indicates that the returned duration_in_traffic should be the best estimate of travel time given what is known about both historical traffic conditions and live traffic. Live traffic becomes more important the closer the departure_time is to now.
    • pessimistic indicates that the returned duration_in_traffic should be longer than the actual travel time on most days, though occasional days with particularly bad traffic conditions may exceed this value.
    • optimistic indicates that the returnedduration_in_trafficshould be shorter than the actual travel time on most days, though occasional days with particularly good traffic conditions may be faster than this value. The default value ofbest_guesswill give the most useful predictions for the vast majority of use cases. Thebest_guesstravel time prediction may be shorter thanoptimistic, or alternatively, longer thanpessimistic, due to the way thebest_guess` prediction model integrates live traffic information.

This function returns {:ok, body} if the request is successful, and Google returns data. It returns {:error, error} when there is HTTP errors, or {:error, status} when the request is successful, but Google returns status codes different than “OK”, i.e.:

  • “NOT_FOUND”
  • “ZERO_RESULTS”
  • “MAX_WAYPOINTS_EXCEEDED”
  • “INVALID_REQUEST”
  • “OVER_QUERY_LIMIT”
  • “REQUEST_DENIED”
  • “UNKNOWN_ERROR”
get(endpoint, params)
get(url, headers \\ [], options \\ []) 
get(binary, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a GET request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

get!(url, headers \\ [], options \\ []) 
get!(binary, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a GET request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

head(url, headers \\ [], options \\ []) 
head(binary, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a HEAD request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

head!(url, headers \\ [], options \\ []) 
head!(binary, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a HEAD request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

options(url, headers \\ [], options \\ []) 
options(binary, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues an OPTIONS request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

options!(url, headers \\ [], options \\ []) 
options!(binary, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a OPTIONS request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

patch(url, body, headers \\ [], options \\ []) 
patch(binary, body, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a PATCH request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

patch!(url, body, headers \\ [], options \\ []) 
patch!(binary, body, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a PATCH request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

post(url, body, headers \\ [], options \\ []) 
post(binary, body, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a POST request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

post!(url, body, headers \\ [], options \\ []) 
post!(binary, body, headers, Keyword.t) ::
  HTTPoison.Response.t |
  HTTPoison.AsyncResponse.t

Issues a POST request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

process_response_body(body)
process_url(url)
put(url, body \\ "", headers \\ [], options \\ []) 
put(binary, body, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues a PUT request to the given url.

Returns {:ok, response} if the request is successful, {:error, reason} otherwise.

See request/5 for more detailed information.

put!(url, body \\ "", headers \\ [], options \\ [])

Issues a PUT request to the given url, raising an exception in case of failure.

If the request does not fail, the response is returned.

See request!/5 for more detailed information.

request(method, url, body \\ "", headers \\ [], options \\ []) 
request(atom, binary, body, headers, Keyword.t) ::
  {:ok, HTTPoison.Response.t | HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Issues an HTTP request with the given method to the given url.

This function is usually used indirectly by get/3, post/4, put/4, etc

Args:

  • method - HTTP method as an atom (:get, :head, :post, :put, :delete, etc.)
  • url - target url as a binary string or char list
  • body - request body. See more below
  • headers - HTTP headers as an orddict (e.g., [{"Accept", "application/json"}])
  • options - Keyword list of options

Body:

  • binary, char list or an iolist
  • {:form, [{K, V}, ...]} - send a form url encoded
  • {:file, "/path/to/file"} - send a file

Options:

  • :timeout - timeout to establish a connection, in milliseconds. Default is 8000
  • :recv_timeout - timeout used when receiving a connection. Default is 5000
  • :stream_to - a PID to stream the response to
  • :async - if given :once, will only stream one message at a time, requires call to stream_next
  • :proxy - a proxy to be used for the request; it can be a regular url or a {Host, Proxy} tuple
  • :proxy_auth - proxy authentication {User, Password} tuple
  • :ssl - SSL options supported by the ssl erlang module
  • :follow_redirect - a boolean that causes redirects to be followed
  • :max_redirect - an integer denoting the maximum number of redirects to follow
  • :params - an enumerable consisting of two-item tuples that will be appended to the url as query string parameters

Timeouts can be an integer or :infinity

This function returns {:ok, response} or {:ok, async_response} if the request is successful, {:error, reason} otherwise.

Examples 

request(:post, "https://my.website.com", "{\"foo\": 3}", [{"Accept", "application/json"}])
request!(method, url, body \\ "", headers \\ [], options \\ []) 
request!(atom, binary, body, headers, Keyword.t) :: HTTPoison.Response.t

Issues an HTTP request with the given method to the given url, raising an exception in case of failure.

request!/5 works exactly like request/5 but it returns just the response in case of a successful request, raising an exception in case the request fails.

start()

Starts HTTPoison and its dependencies.

stream_next(async_response) 
stream_next(HTTPoison.AsyncResponse.t) ::
  {:ok, HTTPoison.AsyncResponse.t} |
  {:error, HTTPoison.Error.t}

Requests the next message to be streamed for a given HTTPoison.AsyncResponse.

See request!/5 for more detailed information.