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. Here's an example:

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

// To use HTTPS, use:
client.SetHTTPS(true)

// To use your own http.Client:
client.SetHTTPClient(myClient)

// To log request and response, set a logger:
logger := log.New(os.Stderr, "", 0)
client.SetLogger(logger)

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: &mapquest.GeoPoint{
    Longitude: 11.54165,
    Latitude:  48.151313,
  },
  Zoom:   9,
  Width:  500,
  Height: 300,
  Format: "png",
}
img, err := client.StaticMap().Get(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.

req := &mapquest.GeocodingAddressRequest{
  Location: &mapquest.GeocodingLocation{
    Street:     "1090 N Charlotte St",
    City:       "Lancaster",
    State:      "PA",
    PostalCode: "17603",
  },
}
res, err := client.Geocoding().Address(req)
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.

req := &mapquest.NominatimSearchRequest{
  Query: "Unter den Linden 117, Berlin, DE",
  Limit: 1,
}
res, err := client.Nominatim().Search(req)
if err != nil {
  panic(err)
}

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

Contributors

• Oliver Eilhard (original 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>")

    // To use HTTPS, use:
    client.SetHTTPS(true)

    // To use your own http.Client:
    client.SetHTTPClient(myClient)

    // To log request and response, set a logger:
    logger := log.New(os.Stderr, "", 0)
    client.SetLogger(logger)

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: &mapquest.GeoPoint{
        Longitude: 11.54165,
        Latitude:  48.151313,
      },
      Zoom:   9,
      Width:  500,
      Height: 300,
      Format: "png",
    }
    img, err := client.StaticMap().Get(req)
    if err != nil {
      panic(err)
	}

To use the Geocoding API, issue a request like this:

req := &mapquest.GeocodingAddressRequest{
  Location: &mapquest.GeocodingLocation{
    Street:     "1090 N Charlotte St",
    City:       "Lancaster",
    State:      "PA",
    PostalCode: "17603",
  },
}
res, err := client.Geocoding().Address(req)
if err != nil {
  panic(err)
}

The Nominatim API can be used as follows:

req := &mapquest.NominatimSearchRequest{
  Query: "Unter den Linden 117, Berlin, DE",
  Limit: 1,
}
res, err := client.Nominatim().Search(req)
if err != nil {
  panic(err)
}

Index

• Constants
• type Client
  • func NewClient(key string) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) Geocoding() *GeocodingAPI
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) HTTPS() bool
  • func (c *Client) Nominatim() *NominatimAPI
  • func (c *Client) SetHTTPClient(client *http.Client)
  • func (c *Client) SetHTTPS(https bool)
  • func (c *Client) SetLogger(logger *log.Logger)
  • func (c *Client) StaticMap() *StaticMapAPI
• type GeoBox
• type GeoPoint
• type GeocodingAPI
  • func (api *GeocodingAPI) Address(req *GeocodingAddressRequest) (*GeocodingAddressResponse, error)
• type GeocodingAddressRequest
• type GeocodingAddressResponse
• type GeocodingAddressResponseLocation
• type GeocodingAddressResponseResults
• type GeocodingLocation
• type NominatimAPI
  • func (api *NominatimAPI) Search(req *NominatimSearchRequest) (*NominatimSearchResponse, error)
• type NominatimSearchRequest
• type NominatimSearchResponse
• type NominatimSearchResult
• type PointOfInterest
• type StaticMapAPI
  • func (api *StaticMapAPI) Get(req *StaticMapRequest) (image.Image, error)
• type StaticMapRequest

Constants

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

const (
	// GeocodingPathPrefix is the default path prefix for the Geocoding API.
	GeocodingPathPrefix = "/geocoding/v1"
)

const (
	// NominatimPathPrefix is the default path prefix for the Nominatim API.
	NominatimPathPrefix = "/nominatim/v1"
)

const (
	// StaticMapPathPrefix is the default path prefix for the Static Map API.
	StaticMapPathPrefix = "/staticmap/v4"
)

Types

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 http://developer.mapquest.com/web/products/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) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the base URL to access the MapQuest API. Example: https://open.mapquestapi.com (without the trailing slash).

func (*Client) Geocoding

func (c *Client) Geocoding() *GeocodingAPI

Geocoding gives access to the MapQuest geocoding API described here: http://open.mapquestapi.com/geocoding/

func (*Client) HTTPClient

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

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

func (*Client) HTTPS

func (c *Client) HTTPS() bool

HTTPS returns true if the client is configured to use HTTPS, false otherwise.

func (*Client) Nominatim

func (c *Client) Nominatim() *NominatimAPI

Nominatim is a gateway to the Nominatim API provided by MapQuest. See http://open.mapquestapi.com/nominatim/ for details.

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) SetHTTPS

func (c *Client) SetHTTPS(https bool)

SetHTTPS tells the client whether to use HTTPS or HTTP.

func (*Client) SetLogger

func (c *Client) SetLogger(logger *log.Logger)

SetLogger sets the logger to use when e.g. debugging requests. Set to nil to disable logging (the default).

func (*Client) StaticMap

func (c *Client) StaticMap() *StaticMapAPI

StaticMap gives access to the MapQuest static map API described here: http://open.mapquestapi.com/staticmap/

type GeoBox

type GeoBox struct {
	A GeoPoint
	B GeoPoint
}

type GeoPoint

type GeoPoint struct {
	Latitude  float64
	Longitude float64
}

type GeocodingAPI

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

GeocodingAPI enables users to take an address and get the associated latitude and longitude from the MapQuest API. See http://open.mapquestapi.com/geocoding/ for details.

func (*GeocodingAPI) Address

func (api *GeocodingAPI) Address(req *GeocodingAddressRequest) (*GeocodingAddressResponse, error)

Address returns information about a specific address.

type GeocodingAddressRequest

type GeocodingAddressRequest struct {
	Location *GeocodingLocation `json:"location,omitempty"`
}

type GeocodingAddressResponse

type GeocodingAddressResponse struct {
	Options struct {
		IgnoreLatLngInput bool `json:"ignoreLatLngInput,omitempty"`
		MaxResults        int  `json:"maxResults,omitempty"`
		ThumbMaps         bool `json:"thumbMaps,omitempty"`
	} `json:"options,omitempty"`
	Results []*GeocodingAddressResponseResults `json:"results,omitempty"`
}

type GeocodingAddressResponseLocation

type GeocodingAddressResponseLocation struct {
	AdminArea1     string `json:"adminArea1,omitempty"`
	AdminArea1Type string `json:"adminArea1Type,omitempty"`
	AdminArea2     string `json:"adminArea2,omitempty"`
	AdminArea2Type string `json:"adminArea2Type,omitempty"`
	AdminArea3     string `json:"adminArea3,omitempty"`
	AdminArea3Type string `json:"adminArea3Type,omitempty"`
	AdminArea4     string `json:"adminArea4,omitempty"`
	AdminArea4Type string `json:"adminArea4Type,omitempty"`
	AdminArea5     string `json:"adminArea5,omitempty"`
	AdminArea5Type string `json:"adminArea5Type,omitempty"`
	DisplayLatLng  *struct {
		Latitude  float64 `json:"lat,omitempty"`
		Longitude float64 `json:"lng,omitempty"`
	} `json:"displayLatLng,omitempty"`
	DragPoint          *bool  `json:"dragPoint,omitempty"`
	GeocodeQuality     string `json:"geocodeQualtity,omitempty"`
	GeocodeQualityCode string `json:"geocodeQualtityCode,omitempty"`
	LatLng             *struct {
		Latitude  float64 `json:"lat,omitempty"`
		Longitude float64 `json:"lng,omitempty"`
	} `json:"latLng,omitempty"`
	LinkId       int    `json:"linkId,omitempty"`
	MapUrl       string `json:"mapUrl,omitempty"`
	PostalCode   string `json:"postalCode,omitempty"`
	SideOfStreet string `json:"sideOfStreet,omitempty"`
	Street       string `json:"street,omitempty"`
	Type         string `json:"type,omitempty"`
}

type GeocodingAddressResponseResults

type GeocodingAddressResponseResults struct {
	Locations        []*GeocodingAddressResponseLocation `json:"locations,omitempty"`
	ProvidedLocation *GeocodingLocation                  `json:"providedLocation,omitempty"`
}

type GeocodingLocation

type GeocodingLocation struct {
	LatLng     string `json:"latLng,omitempty"`
	Street     string `json:"street,omitempty"`
	City       string `json:"city,omitempty"`
	County     string `json:"county,omitempty"`
	State      string `json:"state,omitempty"`
	Country    string `json:"country,omitempty"`
	PostalCode string `json:"postalCode,omitempty"`
	Type       string `json:"type,omitempty"`
	DragPoint  *bool  `json:"dragPoint,omitempty"`
}

type NominatimAPI

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

NominatimAPI is a geographic search service that relies solely on the data contributed to OpenStreetMap. See http://open.mapquestapi.com/nominatim/ for details.

func (*NominatimAPI) Search

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

Search searches for details given an address.

type NominatimSearchRequest

type NominatimSearchRequest struct {
	Query           string
	Street          string
	City            string
	County          string
	State           string
	Country         string
	PostalCode      string
	Limit           int
	CountryCodes    []string
	ViewBox         []float64
	ExcludePlaceIds []string
	Bounded         *bool
	RouteWidth      *float64
	OSMType         string
	OSMId           string
}

type NominatimSearchResponse

type NominatimSearchResponse struct {
	Results []*NominatimSearchResult
}

type NominatimSearchResult

type NominatimSearchResult 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?
}

type PointOfInterest

type PointOfInterest struct {
	// Label is the name of the icon to display.
	// See http://open.mapquestapi.com/staticmap/icons.html for
	// the list of valid icons.
	Label string

	// Latitude of the point of interest.
	Latitude float64

	// Longitude of the point of interest.
	Longitude float64

	// OffsetX is the offset on the x axis. It is optional.
	OffsetX int

	// OffsetY is the offset on the y axis. It is optional.
	OffsetY int
}

PointOfInterest defines an interesting point to be displayed on a map.

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) Get

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

Get returns an image of static map by querying MapQuest.

type StaticMapRequest

type StaticMapRequest struct {
	// Center defines the center point for the map image.
	Center *GeoPoint

	// Bestfit defines a bounding box to be used to specify
	// the area of the map to be shown. This can be used
	// instead of Center.
	Bestfit *GeoBox

	// Margin can adjust the zoom level accordingly when
	// you are out of bounds of the map. Use this in
	// combination with Bestfit.
	Margin int

	// Width of the map. The width must not be greater than 3840.
	Width int

	// Height of the map. The height must not be greater than 3840.
	Height int

	// Zoom specifies the zoom level, which is in the
	// range of 1 (world view) to 18 (most details).
	// See http://open.mapquestapi.com/staticmap/zoomToScale.html
	// for details and scale.
	Zoom int

	// Scale specifies the display scale for the map image,
	// in the range of 1-18 (see Zoom).
	// You must specify a scale when you use the Center property
	// and you do not specify a zoom level.
	Scale int

	// Type specifies the map mode. It can be "map", "sat", or "hyb".
	// The default is "map".
	Type string

	// Format specifies the image format. Valid values are
	// "jpeg", "jpg", "gif", and "png". The default is "jpg".
	Format string

	// PointsOfInterest enlists the various points of interest to be
	// displayed on the map.
	PointsOfInterest []*PointOfInterest
}