geocodexyz

README

Go Geocode.xyz Client

This is a simple client for the Geocode.xyz API. This is in the very, very early testing stages, so should not be used by anyone. We welcome contributors, but we strongly recommend you reach out first to ensure that your work and efforts will be in-line with our design, scope, and goals.

THE API CAN, AND WILL, CHANGE! Do not use until this message is removed. This is in a prototyping stage and may never be completed.

Use Case

Using this library, you can make calls to the Geocode.xyz API. This library was developed for a proof of concept explring options for reverse geocoding APIs for an employer. It is not battlehardened and is designed to test integrating with the service. It does not intend to be a full-coverage SDK and may not be production-ready if another alternative is used.

US-focus

As the primary audience of the client has customers solely in the US, the focus of the Reverse Geocode Lookup is to find a street, city, state, postal, and country. As such, returns that do not have those fields, and cannot by marshalled into a full result object, will return an error instead.

Testing

Note that without an auth key, your testing may not be complete. For example, if you are rate limited, the "success" path in the tests will not pass, since the error handling would be called.

Contributing

Pull Requests are welcome! See our CONTRIBUTING.md file for more information.

Documentation

Index

• func ReverseLookup(input *ReverseLookupRequest) (*ReverseLocationResult, *APIError, error)
• type APIError
  • func (input *APIError) Error() string
• type LocationLookupResult
• type ReverseLocationLookupAPIResult
• type ReverseLocationResult
• type ReverseLookupRequest

Functions

func ReverseLookup

func ReverseLookup(input *ReverseLookupRequest) (*ReverseLocationResult, *APIError, error)

ReverseLookup performs a reverse lookup based upon the provided parameters. At a minimum, you should provide the Lat and Lng fields

Types

type APIError

type APIError struct {
	Description string `json:"description"`
	Code        string `json:"code"`
	Requests    int    `json:"requests"`
}

APIError holds information about the rate limit or location miss errors

func (*APIError) Error

func (input *APIError) Error() string

type LocationLookupResult

type LocationLookupResult struct {
	Standard struct {
		Stnumber string `json:"stnumber"`
		Addresst string `json:"addresst"`
		Postal   struct {
		} `json:"postal"`
		Region string `json:"region"`
		Zip    struct {
		} `json:"zip"`
		Prov        string `json:"prov"`
		City        string `json:"city"`
		Countryname string `json:"countryname"`
		Confidence  string `json:"confidence"`
	} `json:"standard"`
	Longt string `json:"longt"`
	Alt   struct {
	} `json:"alt"`
	Elevation struct {
	} `json:"elevation"`
	Latt string `json:"latt"`
}

LocationLookupResult is a successful lookup for a location passed in, such as "123 Main Street, Salem, NH"

type ReverseLocationLookupAPIResult

type ReverseLocationLookupAPIResult struct {
	Statename string `json:"statename"`
	Distance  string `json:"distance"`
	Elevation string `json:"elevation"`
	Osmtags   struct {
		Wikipedia  string `json:"wikipedia"`
		Wikidata   string `json:"wikidata"`
		Place      string `json:"place"`
		Name       string `json:"name"`
		LandArea   string `json:"land_area"`
		AdminLevel string `json:"admin_level"`
		Boundary   string `json:"boundary"`
		Type       string `json:"type"`
	} `json:"osmtags"`
	State     string `json:"state"`
	Latt      string `json:"latt"`
	City      string `json:"city"`
	Prov      string `json:"prov"`
	Geocode   string `json:"geocode"`
	Geonumber string `json:"geonumber"`
	Country   string `json:"country"`
	Stnumber  string `json:"stnumber,omitempty"`
	Staddress string `json:"staddress"`
	Inlatt    string `json:"inlatt"`
	Alt       struct {
		Loc []struct {
			Staddress string `json:"staddress"`
			Stnumber  string `json:"stnumber"`
			Postal    string `json:"postal"`
			Latt      string `json:"latt"`
			City      string `json:"city"`
			Prov      string `json:"prov"`
			Longt     string `json:"longt"`
			Class     struct {
			} `json:"class"`
			Dist string `json:"dist"`
		} `json:"loc"`
	} `json:"alt"`
	Timezone         string `json:"timezone"`
	Region           string `json:"region"`
	Postal           string `json:"postal"`
	Longt            string `json:"longt"`
	RemainingCredits struct {
	} `json:"remaining_credits"`
	Confidence string `json:"confidence"`
	Inlongt    string `json:"inlongt"`
	Class      struct {
	} `json:"class"`
	Adminareas struct {
		Admin6 struct {
			Wikipedia        string `json:"wikipedia"`
			Wikidata         string `json:"wikidata"`
			Population       string `json:"population"`
			Name             string `json:"name"`
			SourcePopulation string `json:"source_population"`
			NistStateFips    string `json:"nist_state_fips"`
			AdminLevel       string `json:"admin_level"`
			NistFipsCode     string `json:"nist_fips_code"`
			Level            string `json:"level"`
			Boundary         string `json:"boundary"`
			Type             string `json:"type"`
			BorderType       string `json:"border_type"`
		} `json:"admin6"`
		Admin8 struct {
			Wikipedia  string `json:"wikipedia"`
			Wikidata   string `json:"wikidata"`
			Place      string `json:"place"`
			Name       string `json:"name"`
			LandArea   string `json:"land_area"`
			AdminLevel string `json:"admin_level"`
			Level      string `json:"level"`
			Boundary   string `json:"boundary"`
			Type       string `json:"type"`
		} `json:"admin8"`
	} `json:"adminareas"`
	Altgeocode string `json:"altgeocode"`
}

ReverseLocationLookupAPIResult is the raw return for a location look up. Not all fields are always returned. Note the remote API converts everything to strings, including elevation, etc. So it's challenging to convert them correctly here. You may want to check their values and convert them by hand. Often, you will use the simpler version below.

type ReverseLocationResult

type ReverseLocationResult struct {
	Lat        float64                         `json:"lat"`
	Lng        float64                         `json:"lng"`
	Street     string                          `json:"street"`
	City       string                          `json:"city"`
	State      string                          `json:"state"`
	Postal     string                          `json:"postal"`
	Country    string                          `json:"country"`
	Confidence float64                         `json:"confidence"`
	RawRequest *ReverseLocationLookupAPIResult `json:"raw"`
}

ReverseLocationResult is the main result used by the look up and simplifies some of the values

type ReverseLookupRequest

type ReverseLookupRequest struct {
	LanguageCode string  `json:"language"`
	Region       string  `json:"region"`
	Lat          float64 `json:"lat"`
	Lng          float64 `json:"lng"`
}

ReverseLookupRequest is the request sent to the API requesting the json data