labzero / elm-google-geocoding / Geocoding

This library is an interface to Google's geocoding service

https://developers.google.com/maps/documentation/geocoding/intro

It provides a pipline friendly, builder-like API, and ADTs that map as closely as possible to the Google API

You can start building a request one of two ways:

Geocoding.requestForAddress apiKey "77 Battery St."
Geocoding.requestForComponents
  [
    ("Spain", Geocoding.CountryComponent)
  ]

or for reverse geocoding: Geocoding.reverseRequestForLatLng apiKey ( 37.8489277, -122.4031502 ) Geocoding.reverseRequestForPlaceId apiKey "ChIJrTLr-GyuEmsRBfy61i59si0"

Once you've built your request, calling send will return a Http.Request, which you perform to generate your own msg types

Types


type alias GeocodingResult =
{ addressComponents : List AddressComponent
, formattedAddress : String
, geometry : Geometry
, types : List ComponentType
, placeId : String 
}

an individual result https://developers.google.com/maps/documentation/geocoding/intro#Results


type Status
    = GeocodingOk
    | ZeroResults
    | OverQueryLimit
    | RequestDenied
    | InvalidRequest
    | UnknownError

mapping of Google API response statuses https://developers.google.com/maps/documentation/geocoding/intro#StatusCodes


type alias Viewport =
{ northeast : Location
, southwest : Location 
}

a bounding box https://developers.google.com/maps/documentation/geocoding/intro#Viewports


type alias ApiKey =
String

alias for a Google API key


type Component
    = RouteComponent
    | LocalityComponent
    | AdministrativeAreaComponent
    | PostalCodeComponent
    | CountryComponent

components for request filtering https://developers.google.com/maps/documentation/geocoding/intro#ComponentFiltering


type LocationType
    = Rooftop
    | RangeInterpolated
    | GeometricCenter
    | Approximate
    | OtherLocationType

additional data about a location https://developers.google.com/maps/documentation/geocoding/intro#Result


type ComponentType
    = StreetAddress
    | Route
    | Intersection
    | Political
    | Country
    | AdministrativeAreaLevel1
    | AdministrativeAreaLevel2
    | AdministrativeAreaLevel3
    | AdministrativeAreaLevel4
    | AdministrativeAreaLevel5
    | ColloquialArea
    | Locality
    | Sublocality
    | SublocalityLevel1
    | SublocalityLevel2
    | SublocalityLevel3
    | SublocalityLevel4
    | SublocalityLevel5
    | Neighborhood
    | Premise
    | Subpremise
    | PostalCode
    | NaturalFeature
    | Airport
    | Park
    | PostBox
    | StreetNumber
    | Floor
    | Room
    | Establishment
    | PointOfInterest
    | Parking
    | PostalTown
    | BusStation
    | TrainStation
    | TransitStation
    | PostalCodeSuffix
    | OtherComponent

address component types https://developers.google.com/maps/documentation/geocoding/intro#Types


type alias Response =
{ status : Status
, results : List GeocodingResult 
}

response status and a list of results (list will be empty if status is other than OK) https://developers.google.com/maps/documentation/geocoding/intro#GeocodingResponses

Building a request

requestForAddress : ApiKey -> String -> GeocodingRequest

Build a request for an address

Geocoding.requestForAddress apiKey "77 Battery St"

requestForComponents : ApiKey -> List ( String, Component ) -> GeocodingRequest

Build a request for a list of component filters

Geocoding.requestForComponents apiKey
  [
    ("Spain", Geocoding.CountryComponent)
  , ("Toledo", Geocoding.AdministrativeAreaComponent)
  ]

withAddress : String -> GeocodingRequest -> GeocodingRequest

set the address to a request. If called more than once, the later call overwrites the earlier

Geocoding.requestForComponents apiKey
  [
    ("Spain", Geocoding.CountryComponent)
  , ("Toledo", Geocoding.AdministrativeAreaComponent)
  ]
    |> Geocoding.withAddress "Toledo"

withComponent : ( String, Component ) -> GeocodingRequest -> GeocodingRequest

add a component filter to a request (can be called more than once for a request)

Geocoding.requestForAddress apiKey "Toledo"
  |> Geocoding.withComponent ("Spain", Geocoding.CountryComponent)

withLanguage : String -> GeocodingRequest -> GeocodingRequest

Specify the language for the request

Geocoding.requestForAddress apiKey "77 Battery St"
  |> Geocoding.withLanguage("FR")

withRegion : String -> GeocodingRequest -> GeocodingRequest

specify region biasing for request

Geocoding.requestForAddress apiKey "Toledo"
  |> Geocoding.withRegion "ES"

withBounds : ( Basics.Float, Basics.Float ) -> ( Basics.Float, Basics.Float ) -> GeocodingRequest -> GeocodingRequest

Specify a viewport bias for the request

Geocoding.requestForAddress apiKey "Belmont"
  |> Geocoding.withBounds (41, -74) (42, -70)

Building a reverse geocoding request

reverseRequestForLatLng : ApiKey -> ( Basics.Float, Basics.Float ) -> ReverseGeocodingRequest

Build a reverse geocoding request for an location

Geocoding.reverseRequestForLatLng apiKey (37.8489277,-122.4031502)

reverseRequestForPlaceId : ApiKey -> String -> ReverseGeocodingRequest

Build a reverse geocoding request for Google place_id

Geocoding.reverseRequestForLatLng apiKey "ChIJrTLr-GyuEmsRBfy61i59si0"

reverseWithLanguage : String -> ReverseGeocodingRequest -> ReverseGeocodingRequest

Set the language for the request

Geocoding.reverseRequestForLatLng apiKey "ChIJrTLr-GyuEmsRBfy61i59si0"
  |> Geocoding.reverseWithLanguage("FR")

withResultTypes : List ComponentType -> ReverseGeocodingRequest -> ReverseGeocodingRequest

Set the result type(s) for the request

Geocoding.reverseRequestForLatLng apiKey (37.8489277,-122.4031502)
  |> Geocoding.withResultTypes [Country, PostalCode]

withLocationTypes : List LocationType -> ReverseGeocodingRequest -> ReverseGeocodingRequest

Set the location type filters for the request

Geocoding.reverseRequestForLatLng apiKey (37.8489277,-122.4031502)
  |> Geocoding.withLocationTypes [Approximate]

Sending a request

send : (Result Http.Error Response -> msg) -> GeocodingRequest -> Platform.Cmd.Cmd msg

transform a GeocodingRequest into a Cmd

Geocoding.requestForAddress apiKey "77 Battery St"
  |> Geocoding.send MyGeocoderResult

sendReverseRequest : (Result Http.Error Response -> msg) -> ReverseGeocodingRequest -> Platform.Cmd.Cmd msg

transform a reverse geocoding request into a Cmd

Geocoding.requestForLatLng apiKey (37.8489277,-122.4031502)
  |> Geocoding.sendReverseRequest MyReverseGeocoderResult

Inspecting a request

requestUrl : GeocodingRequest -> String

for inspecting the request URL for testing purposes

reverseRequestUrl : ReverseGeocodingRequest -> String

for inspecting the request URL for testing purposes