nomi

Documentation

Overview

Package nomi provides a client to the Nominatiom webservice from OpenStreetMaps.org. It features Redis-backed caching and automatic request rate limiting in respect of Nominatim's Usage Policy.

Index

• Variables
• type Address
• type Box
  • func NewBox(leftUpper Point, rightLower Point) *Box
• type Client
  • func NewClient(opt *ClientOptions) (*Client, error)
  • func (c *Client) Search(params SearchParams, options SearchOptions) (SearchResponse, error)
  • func (c *Client) UseCache(redisURL string) error
• type ClientOptions
• type Place
• type Point
  • func NewPoint(lat float64, lng float64) *Point
  • func (p *Point) Lat() float64
  • func (p *Point) Lng() float64
• type SearchOptions
• type SearchParams
• type SearchResponse

Variables

var (
	DefaultClientOptions = ClientOptions{
		Endpoint: "https://nominatim.openstreetmap.org",
		MaxRPS:   1,
	}
)

Types

type Address

type Address struct {
	City           string `json:"city"`
	CityDistrict   string `json:"city_district"`
	Construction   string `json:"construction"`
	Continent      string `json:"continent"`
	County         string `json:"country"`
	State          string `json:"state"`
	Country        string `json:"country"`
	CountryCode    string `json:"country_code"`
	HouseNumber    string `json:"house_number"`
	Neighbourhood  string `json:"neighbourhood"`
	Postcode       string `json:"postcode"`
	PublicBuilding string `json:"public_building"`
	Suburb         string `json:"suburb"`
}

type Box

type Box struct {
	LeftUpper  Point
	RightLower Point
}

Box represents a bounding box defined by left upper and right lower corner

func NewBox

func NewBox(leftUpper Point, rightLower Point) *Box

NewBox returns a new Box populated by the passed values

type Client

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

func NewClient

func NewClient(opt *ClientOptions) (*Client, error)

NewClient returns a client to Nominatim specified by options.

func (*Client) Search

func (c *Client) Search(params SearchParams, options SearchOptions) (SearchResponse, error)

func (*Client) UseCache

func (c *Client) UseCache(redisURL string) error

type ClientOptions

type ClientOptions struct {
	// Endpoint defaults to Nominatim server from OpenStreetMaps.
	// Overwrite to use a 3rd party or your own server.
	Endpoint  string
	Email     string
	UserAgent string

	// MaxRPS specifies the maximum requests per second a client is allowed to make.
	// It will slow down automatically to meet this value.
	// Nominatim allows a maximum of 1 rps, which is used as a default if
	// value is not specified.
	MaxRPS int64
}

type Place

type Place struct {
	PlaceID     int      `json:"place_id"`
	Licence     string   `json:"licence"`
	OSMType     string   `json:"osm_type"`
	OSMID       int      `json:"osm_id"`
	Boundingbox []string `json:"boundingbox"`
	Lon         string   `json:"lon"`
	Lat         string   `json:"lat"`
	DisplayName string   `json:"display_name"`

	// PlaceRank is based on a rather complex algorithm taking the place type
	// and various other attributes into account. For example it seems checks
	// whether this object is a village, a city, a country, a continent,
	// a highway, a lake and similar other properties.
	PlaceRank  int     `json:"place_rank"`
	Category   string  `json:"category"`
	Class      string  `json:"class"`
	Type       string  `json:"type"`
	Importance float64 `json:"importance"`
	Icon       string  `json:"icon"`

	Address Address `json:"address"`
}

type Point

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

Point represents a physical point in geographic notation [lat, lng]

func NewPoint

func NewPoint(lat float64, lng float64) *Point

NewPoint returns a new Point populated by the passed coordinates

func (*Point) Lat

func (p *Point) Lat() float64

Lat returns Point p's latitude

func (*Point) Lng

func (p *Point) Lng() float64

Lng returns Point p's longitude

type SearchOptions

type SearchOptions struct {
	AcceptLanguage string
	Limit          int  // Defaults to 10
	Dedupe         bool // Defaults to true

	// Include a breakdown of the address into elements
	IncludeAddressDetails bool
}

type SearchParams

type SearchParams struct {
	// i.e. "Zurich, Switzerland"
	Query string

	// Query and the following options are mutually exclusive. Query has precedence.
	Street     string
	City       string
	County     string
	State      string
	Country    string
	Postalcode string

	// Limit search results to a specific country (or a list of countries).
	// Should be the ISO 3166-1alpha2 code, e.g. gb for the United Kingdom, de for Germany, etc.
	CountryCodes []string

	// The preferred area to find search results. Any two corner points of the box are accepted in any order as long as they span a real box.
	Viewbox *Box

	//    Restrict the results to only items contained with the viewbox (see above).
	//    Restricting the results to the bounding box also enables searching by amenity only.
	Bounded bool
}

type SearchResponse

type SearchResponse []Place