# (lisppad location)
Library `(lisppad location)` implements procedures for geocoding and reverse geocoding and provides representations of *locations* (latitude, longitude, altitude) and *places* (structured representation of addresses).
## 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 the current device location. If a device location can't be determined, the procedure returns `#f`. The procedure also returns `#f` if the user did not authorize the device to reveal the location to LispPad.
**(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.
## 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 list of locations for 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. `geocode` signals an error if the geocoding operation fails (e.g. if there is no network access).
```scheme
(geocode "Brandschenkestrasse 110, Zürich" 'de_CH)
⇒ ((47.3654121 8.5247038))
```
**(reverse-geocode *****loc*****)** \
\&#xNAN;**(reverse-geocode *****loc locale*****)**\
\&#xNAN;**(reverse-geocode *****lat long*****)**\
\&#xNAN;**(reverse-geocode *****lat long locale*****)**
Returns a list of places for 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
(reverse-geocode (location 47.36541 8.5247) 'en_US)
⇒ (("CH" "Switzerland" "Zürich" "Zürich"
"8002" "Zürich" "Brunau"
"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 (reverse-geocode (location 47.36541 8.5247) 'de_CH)))
pl ⇒ (("CH" "Schweiz" "Zürich" "Zürich"
"8002" "Zürich" "Brunau"
"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 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
(address->place "Brandschenkestrasse 110, Zürich")
⇒ (("CH" "Switzerland" "Zürich" "Zürich"
"8002" "Zürich" "Brunau"
"Brandschenkestrasse" "110" "Europe/Zurich"))
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.lisppad.app/libraries/lisppad/location.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.