mapquest

README

MapQuest Google Go Client

This is a very first draft of a Google Go client for MapQuest Open Data Map APIs and Web Services.

Status

We just implemented a limited set of APIs: The Static Map API, the Geocoding API, and the Nominatim API. Other APIs will be implemented as needed (pull requests are welcome).

Consider this package beta. The API is not stable and the code probably is not production quality yet. We use it in parts of our applications, but its use is limited. Bugs will be fixed when found. If you find a bug, report it or--even better--send a pull request.

Testing

To run the tests, you need to add a file ACCESS_KEY to the packages root directory. Paste you MapQuest access key there.

Notice that the MapQuest API seems to not like the access key URL-encoded. So make sure you paste it unencoded. For example, a valid access key should look like a bit like this:

Fmjad|lufd281r2q,72=o5-9attor

(Do not use the key above. It's just an example. The key above will not yield valid results. Get your own key instead. It's free!)

After you created the file, you can run tests as usual:

$ go test

Creating a client

To use the various APIs, you first need to create a client.

client := mapquest.NewClient("<your-app-key>")

Now that you have a Client, you can use the APIs.

Static Map API

Here's an example of how to use the MapQuest static map API:

req := &mapquest.StaticMapRequest{
  Center: "11.54165,48.151313",
  Zoom:   9,
  Width:  500,
  Height: 300,
  Format: "png",
}
img, err := client.StaticMap().Map(req)
if err != nil {
  panic(err)
}

You now have an image.Image at hand. Further details can be found in the Open Static Map Service Developer's Guide.

Geocoding API

The Geocoding API enables you to take an address and get the associated latitude and longitude.

res, err := client.Geocoding().SimpleAddress("1090 N Charlotte St, Lancaster", 0)
if err != nil {
  panic(err)
}

Further details can be found in the Open Geocoding Service Developer's Guide.

Nominatim API

The Nominatim API is a search interface that relies solely on the data contributed to OpenStreetMap. It does not require an App-Key.

res, err := client.Nominatim().SimpleSearch("Unter den Linden 117, Berlin, DE", 1)
if err != nil {
  panic(err)
}

Further details can be found in the Nominatim Search Service Developer's Guide

Contributors

• Oliver Eilhard (original author)
• Christopher König (new author)

License

This code comes with a MIT license.

Documentation

Overview

Package mapquest enables access to the Open MapQuest APIs. For further details, see http://open.mapquestapi.com/.

To get started, you need to create a client:

client := mapquest.NewClient("<your-app-key>")

Now that you have a client, you can use the APIs.

Here's an example of how to use the MapQuest static map API:

    req := &mapquest.StaticMapRequest{
      Center: "11.54165,48.151313",
      Zoom:   9,
      Width:  500,
      Height: 300,
      Format: "png",
    }
    img, err := client.StaticMap().Map(req)
    if err != nil {
      panic(err)
	}

Index

• Constants
• Variables
• type BoundingBox
  • func (s *BoundingBox) EncodeValues(key string, v *url.Values) error
• type Client
  • func NewClient(key string) *Client
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) SetHTTPClient(client *http.Client)
  • func (c *Client) StaticMap() *StaticMapAPI
• type GeoPoint
  • func (s *GeoPoint) EncodeValues(key string, v *url.Values) error
  • func (s *GeoPoint) String() string
• type GeocodeAddressRequest
• type GeocodeAddressResponse
• type GeocodeAddressResponseEntry
• type GeocodeAddressResponseLocationEntry
• type GeocodeReverseRequest
• type GeocodeType
• type GeocodingAPI
  • func (api *GeocodingAPI) Address(req *GeocodeAddressRequest) (*GeocodeAddressResponse, error)
  • func (api *GeocodingAPI) Reverse(req *GeocodeReverseRequest) (*GeocodeAddressResponse, error)
  • func (api *GeocodingAPI) SimpleAddress(location string, limit int) (*GeocodeAddressResponse, error)
  • func (api *GeocodingAPI) SimpleReverse(lat, long float64) (*GeocodeAddressResponse, error)
• type NominatimAPI
  • func (api *NominatimAPI) Reverse(req *NominatimReverseRequest) (*NominatimSearchResponseEntry, error)
  • func (api *NominatimAPI) Search(req *NominatimSearchRequest) (*NominatimSearchResponse, error)
  • func (api *NominatimAPI) SimpleReverse(lat, long float64) (*NominatimSearchResponseEntry, error)
  • func (api *NominatimAPI) SimpleSearch(query string, limit int) (*NominatimSearchResponse, error)
• type NominatimOSMType
• type NominatimReverseRequest
• type NominatimSearchRequest
• type NominatimSearchResponse
• type NominatimSearchResponseEntry
• type StaticMapAPI
  • func (api *StaticMapAPI) Map(req *StaticMapRequest) (image.Image, error)
  • func (api *StaticMapAPI) MapReader(req *StaticMapRequest) (io.ReadCloser, error)
• type StaticMapBanner
  • func (s *StaticMapBanner) EncodeValues(key string, v *url.Values) error
• type StaticMapBannerSize
• type StaticMapColor
  • func StaticMapColorHex(h int) *StaticMapColor
  • func StaticMapColorHexAlpha(h int) *StaticMapColor
  • func (s *StaticMapColor) EncodeValues(key string, v *url.Values) error
• type StaticMapFormat
• type StaticMapLocation
  • func (s *StaticMapLocation) EncodeValues(key string, v *url.Values) error
  • func (s *StaticMapLocation) String() string
• type StaticMapLocations
  • func (s StaticMapLocations) EncodeValues(key string, v *url.Values) error
• type StaticMapRequest
• type StaticMapScalebar
  • func (s *StaticMapScalebar) EncodeValues(key string, v *url.Values) error
• type StaticMapShape
• type StaticMapSize
  • func (s *StaticMapSize) EncodeValues(key string, v *url.Values) error
• type StaticMapType

Constants

const (
	GeocodingPrefix  = "geocoding"
	GeocodingVersion = "v1"
)

const (
	Host      = "open.mapquestapi.com"
	UserAgent = "MapQuest Open Data API Google Go Client v0.1"
)

const (
	NominatimPrefix  = "nominatim"
	NominatimVersion = "v1"
)

const (
	OSMTypeNode     NominatimOSMType = "N"
	OSMTypeWay                       = "W"
	OSMTypeRelation                  = "R"
)

const (
	StaticMapPrefix  = "staticmap"
	StaticMapVersion = "v5"
)

const (
	StaticMapFormatPNG   StaticMapFormat = "png"
	StaticMapFormatGIF                   = "gif"
	StaticMapFormatJPEG                  = "jpeg"
	StaticMapFormatJPG                   = "jpg"
	StaticMapFormatJPG70                 = "jpg70"
	StaticMapFormatJPG80                 = "jpg80"
	StaticMapFormatJPG90                 = "jpg90"
)

const (
	StaticMapTypeDark      StaticMapType = "dark"
	StaticMapTypeLight                   = "light"
	StaticMapTypeMap                     = "map"
	StaticMapTypeHybrid                  = "hyb"
	StaticMapTypeSatellite               = "sat"
)

const (
	StaticMapBannerSizeSmall  StaticMapBannerSize = "sm"
	StaticMapBannerSizeMedium                     = "md"
	StaticMapBannerSizeLarge                      = "lg"
)

Variables

var (
	ErrDimensionToLarge = errors.New("dimenstion to large")
)

Types

type BoundingBox

type BoundingBox struct {
	TopLeft     GeoPoint
	BottomRight GeoPoint
}

func (*BoundingBox) EncodeValues

func (s *BoundingBox) EncodeValues(key string, v *url.Values) error

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the entry point to all services of the MapQuest Open Data API. See https://developer.mapquest.com/documentation/open/ for details about what you can do with the MapQuest API.

func NewClient

func NewClient(key string) *Client

NewClient creates a new client for accessing the MapQuest API. You need to specify your AppKey here.

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

HTTPClient returns the registered http.Client. Notice that nil can be returned here.

func (*Client) SetHTTPClient

func (c *Client) SetHTTPClient(client *http.Client)

SetHTTPClient allows the caller to specify a special http.Client for invoking the MapQuest API. If you do not specify a http.Client, the http.DefaultClient from net/http is used.

func (*Client) StaticMap

func (c *Client) StaticMap() *StaticMapAPI

StaticMap gives access to the MapQuest static map API described here: https://developer.mapquest.com/documentation/open/static-map-api/v5/

type GeoPoint

type GeoPoint struct {
	Latitude  float64 `json:"lat"`
	Longitude float64 `json:"lng"`
}

func (*GeoPoint) EncodeValues

func (s *GeoPoint) EncodeValues(key string, v *url.Values) error

func (*GeoPoint) String

func (s *GeoPoint) String() string

type GeocodeAddressRequest

type GeocodeAddressRequest struct {
	Location           string       `url:"location"`
	BoundingBox        *BoundingBox `url:"boundingBox,omitempty"`
	IgnoreLatLongInput bool         `url:"ignoreLatLngInput,omitempty"`
	ThumbMaps          bool         `url:"thumbMaps"` // dont omit, omitempty works on false, default is true though
	Limit              int          `url:"maxResults,omitempty"`
}

type GeocodeAddressResponse

type GeocodeAddressResponse struct {
	Info *struct {
		StatusCode int `json:"statuscode,omitempty"` // https://developer.mapquest.com/documentation/geocoding-api/status-codes
		Copyright  *struct {
			Text         string `json:"text,omitempty"`
			ImageURL     string `json:"imageUrl,omitempty"`
			ImageAltText string `json:"imageAltText,omitempty"`
		} `json:"copyright,omitempty"`
		Messages []string `json:"messages,omitempty"`
	} `json:"info,omitempty"`
	Options *struct {
		MaxResults         int  `json:"maxResults,omitempty"`
		ThumbMaps          bool `json:"thumbMaps"` // dont omit, omitempty works on false, default is true though
		IgnoreLatLongInput bool `json:"ignoreLatLngInput,omitempty"`
	} `json:"options,omitempty"`

	Results []*GeocodeAddressResponseEntry `json:"results,omitempty"`
}

type GeocodeAddressResponseEntry

type GeocodeAddressResponseEntry struct {
	ProvidedLocation *struct {
		Location string    `json:"location,omitempty"`
		LatLong  *GeoPoint `json:"latLng,omitempty"`
	} `json:"providedLocation,omitempty"` // this needs probably 5point support
	Locations []*GeocodeAddressResponseLocationEntry `json:"location,omitempty"`
}

type GeocodeAddressResponseLocationEntry

type GeocodeAddressResponseLocationEntry struct {
	LatLong        *GeoPoint `json:"latLng,omitempty"`
	DisplayLatLong *GeoPoint `json:"displayLatLng,omitempty"`
	MapURL         string    `json:"mapUrl,omitempty"`

	Street         string      `json:"street,omitempty"`
	PostalCode     string      `json:"postalCode,omitempty"`
	Type           GeocodeType `json:"type,omitempty"`
	AdminArea6     string      `json:"adminArea6,omitempty"`
	AdminArea6Type string      `json:"adminArea6Type,omitempty"`
	AdminArea5     string      `json:"adminArea5,omitempty"`
	AdminArea5Type string      `json:"adminArea5Type,omitempty"`
	AdminArea4     string      `json:"adminArea4,omitempty"`
	AdminArea4Type string      `json:"adminArea4Type,omitempty"`
	AdminArea3     string      `json:"adminArea3,omitempty"`
	AdminArea3Type string      `json:"adminArea3Type,omitempty"`
	AdminArea2     string      `json:"adminArea2,omitempty"`
	AdminArea2Type string      `json:"adminArea2Type,omitempty"`
	AdminArea1     string      `json:"adminArea1,omitempty"`
	AdminArea1Type string      `json:"adminArea1Type,omitempty"`

	GeocodeQuality     string `json:"geocodeQuality,omitempty"` // https://developer.mapquest.com/documentation/geocoding-api/quality-codes
	GeocodeQualityCode string `json:"geocodeQualityCode,omitempty"`

	UnkownInput string `json:"unkownInput,omitempty"`

	RoadMetadata *struct {
		SpeedLimitUnits string            `json:"speedLimitUnits,omitempty"`
		TollRoad        []json.RawMessage `json:"TollRoad,omitempty"` // unkown data type, can be nullable
		SpeedLimit      int               `json:"speedLimit,omitempty"`
	} `json:"roadMetadata,omitempty"`

	NearestIntersection *struct {
		StreetDisplayName string    `json:"streetDisplayName,omitempty"`
		DistanceMeters    string    `json:"distanceMeters,omitempty"`
		LatLng            *GeoPoint `json:"latLng,omitempty"`
		Label             string    `json:"label,omitempty"`
	} `json:"nearestIntersection,omitempty"`
}

type GeocodeReverseRequest

type GeocodeReverseRequest struct {
	Location                   *GeoPoint `url:"location"`
	ThumbMaps                  bool      `url:"thumbMaps"` // dont omit, omitempty works on false, default is true though
	IncludeNearestIntersection bool      `url:"includeNearestIntersection,omitempty"`
	IncludeRoadMetadata        bool      `url:"includeRoadMetadata,omitempty"`
}

type GeocodeType

type GeocodeType string

const (
	GeocodeTypeStop GeocodeType = "s"
	GeocodeTypeVia              = "v"
)

type GeocodingAPI

type GeocodingAPI struct {
	// contains filtered or unexported fields
}

GeocodingAPI enables users to request geocoding searches via the MapQuest API. See https://developer.mapquest.com/documentation/open/geocoding-api/ for details. Batch API is not implemented, 5 point queries are not supported

func (*GeocodingAPI) Address

func (api *GeocodingAPI) Address(req *GeocodeAddressRequest) (*GeocodeAddressResponse, error)

func (*GeocodingAPI) Reverse

func (api *GeocodingAPI) Reverse(req *GeocodeReverseRequest) (*GeocodeAddressResponse, error)

func (*GeocodingAPI) SimpleAddress

func (api *GeocodingAPI) SimpleAddress(location string, limit int) (*GeocodeAddressResponse, error)

func (*GeocodingAPI) SimpleReverse

func (api *GeocodingAPI) SimpleReverse(lat, long float64) (*GeocodeAddressResponse, error)

type NominatimAPI

type NominatimAPI struct {
	// contains filtered or unexported fields
}

NominatimAPI enables users to request nominatim searches via the MapQuest API. See https://developer.mapquest.com/documentation/open/nominatim-search/ for details.

func (*NominatimAPI) Reverse

func (api *NominatimAPI) Reverse(req *NominatimReverseRequest) (*NominatimSearchResponseEntry, error)

func (*NominatimAPI) Search

func (api *NominatimAPI) Search(req *NominatimSearchRequest) (*NominatimSearchResponse, error)

func (*NominatimAPI) SimpleReverse

func (api *NominatimAPI) SimpleReverse(lat, long float64) (*NominatimSearchResponseEntry, error)

func (*NominatimAPI) SimpleSearch

func (api *NominatimAPI) SimpleSearch(query string, limit int) (*NominatimSearchResponse, error)

type NominatimOSMType

type NominatimOSMType string

type NominatimReverseRequest

type NominatimReverseRequest struct {
	Latitude  float64          `url:"lat"`
	Longitude float64          `url:"long"`
	OSMType   NominatimOSMType `url:"osm_type,omitempty"`
	OSMID     string           `url:"osm_id,omitempty"`
}

type NominatimSearchRequest

type NominatimSearchRequest struct {
	Query           string           `url:"q"`
	AddressDetails  bool             `url:"addressdetails,omitempty"`
	Limit           int              `url:"limit,omitempty"`
	CountryCodes    []string         `url:"countrycodes,comma,omitempty"`
	ViewBox         *BoundingBox     `url:"viewbox,omitempty"` // let,top,right,bottom => todo
	ExcludePlaceIDs []string         `url:"exclude_place_ids,comma,omitempty"`
	RouteWidth      float64          `url:"routewidth,omitempty"`
	OSMType         NominatimOSMType `url:"osm_type,omitempty"`
	OSMID           string           `url:"osm_id,omitempty"`
}

type NominatimSearchResponse

type NominatimSearchResponse struct {
	Results []*NominatimSearchResponseEntry
}

type NominatimSearchResponseEntry

type NominatimSearchResponseEntry struct {
	Address *struct {
		City          string `json:"city,omitempty"`
		CityDistrict  string `json:"city_district,omitempty"`
		Continent     string `json:"continent,omitempty"`
		Country       string `json:"country,omitempty"`
		CountryCode   string `json:"country_code,omitempty"`
		County        string `json:"county,omitempty"`
		Hamlet        string `json:"hamlet,omitempty"`
		HouseNumber   string `json:"house_number,omitempty"`
		Pedestrian    string `json:"pedestrian,omitempty"`
		Neighbourhood string `json:"neighbourhood,omitempty"`
		PostCode      string `json:"postcode,omitempty"`
		Road          string `json:"road,omitempty"`
		State         string `json:"state,omitempty"`
		StateDistrict string `json:"state_district,omitempty"`
		Suburb        string `json:"suburb,omitempty"`
	} `json:"address,omitempty"`
	BoundingBox []float64 `json:"boundingbox,omitempty"`
	Class       string    `json:"class,omitempty"`
	DisplayName string    `json:"display_name,omitempty"`
	Importance  float64   `json:"importance,omitempty"`
	Latitude    float64   `json:"lat,string,omitempty"`
	Longitude   float64   `json:"lon,string,omitempty"`
	OSMId       string    `json:"osm_id,omitempty"`
	OSMType     string    `json:"osm_type,omitempty"`
	PlaceID     string    `json:"place_id,omitempty"`
	Type        string    `json:"type,omitempty"`
	License     string    `json:"licence,omitempty"` // typo in API
	Icon        string    `json:"icon,omitempty"`
}

type StaticMapAPI

type StaticMapAPI struct {
	// contains filtered or unexported fields
}

StaticMapAPI enables users to request static map images via the MapQuest API. See http://open.mapquestapi.com/staticmap/ for details.

func (*StaticMapAPI) Map

func (api *StaticMapAPI) Map(req *StaticMapRequest) (image.Image, error)

func (*StaticMapAPI) MapReader

func (api *StaticMapAPI) MapReader(req *StaticMapRequest) (io.ReadCloser, error)

type StaticMapBanner

type StaticMapBanner struct {
	Text            string
	Size            StaticMapBannerSize
	OnTop           bool
	TextColor       int // find a way to set 0x000000 without a helper function maybe?
	BackgroundColor int
}

func (*StaticMapBanner) EncodeValues

func (s *StaticMapBanner) EncodeValues(key string, v *url.Values) error

type StaticMapBannerSize

type StaticMapBannerSize string

type StaticMapColor

type StaticMapColor struct {
	R int
	G int
	B int
	A int
}

func StaticMapColorHex

func StaticMapColorHex(h int) *StaticMapColor

func StaticMapColorHexAlpha

func StaticMapColorHexAlpha(h int) *StaticMapColor

func (*StaticMapColor) EncodeValues

func (s *StaticMapColor) EncodeValues(key string, v *url.Values) error

type StaticMapFormat

type StaticMapFormat string

type StaticMapLocation

type StaticMapLocation struct {
	Location string
	Marker   string
}

func (*StaticMapLocation) EncodeValues

func (s *StaticMapLocation) EncodeValues(key string, v *url.Values) error

func (*StaticMapLocation) String

func (s *StaticMapLocation) String() string

type StaticMapLocations

type StaticMapLocations []StaticMapLocation

func (StaticMapLocations) EncodeValues

func (s StaticMapLocations) EncodeValues(key string, v *url.Values) error

type StaticMapRequest

type StaticMapRequest struct {
	Size        *StaticMapSize     `url:"size,omitempty"`
	Center      string             `url:"center,omitempty"`
	BoundingBox *BoundingBox       `url:"boundingBox,omitempty"`
	Margin      int                `url:"margin,omitempty"`
	Zoom        int                `url:"zoom,omitempty"`
	Format      StaticMapFormat    `url:"format,omitempty"`
	Type        StaticMapType      `url:"type,omitempty"`
	Scalebar    *StaticMapScalebar `url:"scalebar,omitempty"`

	// additional location options
	Locations     StaticMapLocations `url:"locations,omitempty"`
	Declutter     bool               `url:"declutter,omitempty"`
	DefaultMarker string             `url:"defaultMarker,omitempty"`

	// banner
	Banner *StaticMapBanner `url:"banner,omitempty"`

	// routes
	Start *StaticMapLocation `url:"start,omitempty"`
	End   *StaticMapLocation `url:"end,omitempty"`
	// TODO: https://developer.mapquest.com/documentation/open/static-map-api/v5/map/#request_parameters-session
	RotueArc   bool            `url:"routeArc,omitempty"`
	RouteWidth int             `url:"routeWidth,omitempty"`
	RouteColor *StaticMapColor `url:"routeColor,omitempty"`
}

type StaticMapScalebar

type StaticMapScalebar struct {
	Enable   bool
	Position string
}

func (*StaticMapScalebar) EncodeValues

func (s *StaticMapScalebar) EncodeValues(key string, v *url.Values) error

type StaticMapShape

type StaticMapShape struct {
}

type StaticMapSize

type StaticMapSize struct {
	Width  int
	Height int
	Retina bool
}

func (*StaticMapSize) EncodeValues

func (s *StaticMapSize) EncodeValues(key string, v *url.Values) error

type StaticMapType

type StaticMapType string