# (lispkit location)
Library `(lispkit location)` implements procedures for geocoding and reverse geocoding and provides representations of *locations* (latitude, longitude, altitude) and *places* (structured representation of addresses). Since geocoding operations take some time, procedures typically return Futures as implemented by library `(lispkit thread future)`.
## Locations
A *location* consists of a latitude, a longitude, and an optional altitude. Locations are represented as lists of two or three flonum values.
**(location? *****obj*****)** 
Returns `#t` if the given expression *obj* is a valid location; returns `#f` otherwise.
**(location *****latitude longitude*****)** \
\&#xNAN;**(location *****latitude longitude altitude*****)**
Creates a location for the given *latitude*, *longitude*, and *altitude*. This procedure fails with an error if any of the provided arguments are not flonum values.
**(current-location)**
Returns a future which eventually refers to the current device location. If a device location can't be determined, the returned future will refer to `#f`. Similarly, the returned future will refer to `#f` if the user did not authorize the device to reveal the location.
**(location-latitude *****loc*****)**
Returns the latitude of location *loc*.
**(location-longitude *****loc*****)**
Returns the longitude of location *loc*.
**(location-altitude *****loc*****)**
Returns the altitude of location *loc*. Since altitudes are optional, procedure `location-altitude` returns `#f` if the altitude is undefined.
**(location-distance *****loc1 loc2*****)**
Returns the distance between location *loc1* and location *loc2* in meters.
**(location->timezone *****loc*****)**
Returns a timezone identifier (string) for location *loc*.
## Places
A *place* is a structured representation describing a place on Earth. Its main components are address components, but a place might also provide meta-information such as the timezone of the place or the ISO country code. Library `(lispkit date-time)` provides more functionality to deal with such meta-data. Places are represented as lists of one to ten strings in the following order:
1. ISO country code
2. Country
3. Region (a part of the country; e.g. State, Bundesland, Kanton, etc.)
4. Administrational region (a part of the region; e.g. County, Landkreis, etc.)
5. Postal code
6. City
7. Locality (a part of the city; e.g. District, Stadtteil, etc.)
8. Street
9. Street number
10. Time zone
Note that all components are optional. An optional component is represented as `#f`.
**(place? *****obj*****)**
Returns `#t` if the given expression *obj* is a valid place; returns `#f` otherwise.
**(place *****code*****)** \
\&#xNAN;**(place *****code country*****)**\
\&#xNAN;**(place *****code country region*****)**\
\&#xNAN;**(place *****code country region admin*****)**\
\&#xNAN;**(place *****code country region admin zip*****)**\
\&#xNAN;**(place *****code country region admin zip city*****)**\
\&#xNAN;**(place *****code country region admin zip city locality*****)**\
\&#xNAN;**(place *****code country region admin zip city locality street*****)**\
\&#xNAN;**(place *****code country region admin zip city locality street nr*****)**\
\&#xNAN;**(place *****code country region admin zip city locality street nr tz*****)**
Returns a location for the given components of a place. Each component is either `#f` (= undefined) or a string.
**(place-country-code *****pl*****)**
Returns the country code for place *pl* as a string or `#f` if the country code is undefined.
**(place-country *****pl*****)**
Returns the country for place *pl* as a string or `#f` if the country is undefined.
**(place-region *****pl*****)**
Returns the region for place *pl* as a string or `#f` if the region is undefined.
**(place-admin *****pl*****)**
Returns the administrational region for place *pl* as a string or `#f` if the administrational region is undefined.
**(place-postal-code *****pl*****)**
Returns the postal code for place *pl* as a string or `#f` if the postal code is undefined.
**(place-city *****pl*****)**
Returns the city for place *pl* as a string or `#f` if the city is undefined.
**(place-locality *****pl*****)**
Returns the locality for place *pl* as a string or `#f` if the locality is undefined.
**(place-street *****pl*****)**
Returns the street for place *pl* as a string or `#f` if the street is undefined.
**(place-street-number *****pl*****)**
Returns the street number for place *pl* as a string or `#f` if the street number is undefined.
**(place-timezone *****pl*****)**
Returns the timezone for place *pl* as a string or `#f` if the timezone is undefined.
## Geocoding
**(geocode *****obj*****)** \
\&#xNAN;**(geocode *****obj locale*****)**
Returns a future for a list of locations at the given place or address. *obj* is either a valid place representation or it is an address string. *locale* is a symbol representing a locale, which is used to interpret the given place or address. The future returned by `geocode` signals an error if the geocoding operation fails, e.g. if there is no network access.
```scheme
(future-get (geocode "Brandschenkestrasse 110, Zürich" 'de_CH))
⇒ ((47.365535 8.524876))
```
**(reverse-geocode *****loc*****)** \
\&#xNAN;**(reverse-geocode *****loc locale*****)**\
\&#xNAN;**(reverse-geocode *****lat long*****)**\
\&#xNAN;**(reverse-geocode *****lat long locale*****)**
Returns a future for a list of places at the given location. *loc* is a valid location. *lat* and *long* describe latitude and longitude as flonums directly. *locale* is a symbol representing a locale. It is used for the place representations returned by `reverse-geocode`.
```scheme
(future-get (reverse-geocode (location 47.36541 8.5247) 'en_US))
⇒ (("CH" "Switzerland" "ZH" "Zürich"
"8002" "Zürich" "Enge"
"Brandschenkestrasse" "110" "Europe/Zurich"))
```
**(place->address *****pl*****)**
Formats a place as an address. For this operation to succeed, it is important that the country code of the place *pl* is set as it is used to determine the address format.
```scheme
(define pl (car (future-get (reverse-geocode (location 47.36541 8.5247) 'de_CH))))
pl ⇒ ("CH" "Schweiz" "ZH" "Zürich"
"8002" "Zürich" "Enge"
"Brandschenkestrasse" "110" "Europe/Zurich")
(display (place->address pl))
⇒
Brandschenkestrasse 110
8002 Zürich
Schweiz
```
**(address->place *****str*****)** \
\&#xNAN;**(address->place *****str locale*****)**
Parses the given address string *str* into a place (or potentially multiple possible places) and returns a future referring to this as a list of places. *locale* is a symbol representing a locale. It is used for the place representations returned by `address->place`.
```scheme
(future-get (address->place "Brandschenkestrasse 110, Zürich"))
⇒ (("CH" "Switzerland" "Zürich" "Zürich"
"8002" "Zürich" "Enge"
"Brandschenkestrasse" "110" "Europe/Zurich"))
```