The open-location-code Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The open-location-code Reference Manual

This is the open-location-code Reference Manual, version 2.1, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 16:20:17 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

An Open Location Code library for Common Lisp.

Open Location Code is a location encoding system for addresses,
independent of street names and building numbers.

See .


The methods requested by the Open Location Code specification
are implemented as follows:

encode (LATITUDE LONGITUDE)  ==>  FULL-CODE
     Convert a latitude and longitude into a 10 digit Open
     Location Code.

encode (LATITUDE LONGITUDE PRECISION)  ==>  FULL-CODE
     Convert a latitude and longitude into an arbitrary
     length Open Location Code.

decode (CODE)  ==>  CODE-AREA
     Decode an Open Location Code into, at a minimum, the
     latitude and longitude of the south-west corner and
     the area's height and width.

validp (CODE)  ==>  boolean
     Determine if a string is a valid sequence of Open
     Location Code characters.

fullp (CODE)  ==>  boolean
     Determine if a string is a valid full Open Location
     Code.

shortp (CODE)  ==>  boolean
     Determine if a string is a valid short Open Location
     Code.

shorten (FULL-CODE LATITUDE LONGITUDE)  ==>  SHORT-CODE
     Remove four or six digits from the front of an Open
     Location Code given a reference location.

recover (SHORT-CODE LATITUDE LONGITUDE)  ==>  FULL-CODE
     Recover a full Open Location Code from a short code
     and a reference location.

See  for more
documentation and sample implementations.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 open-location-code

Author

Ralph Schleicher <rs@ralph-schleicher.de>

License

Modified BSD License

Description

Open Location Code library.

Version

2.1

Dependencies
Source

open-location-code.asd (file)

Component

open-location-code.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 open-location-code.asd

Location

open-location-code.asd

Systems

open-location-code (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 open-location-code/open-location-code.lisp

Parent

open-location-code (system)

Location

open-location-code.lisp

Packages

open-location-code

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 open-location-code

Open Location Code is a location encoding system for addresses, independent of street names and building numbers.

See <https://plus.codes>.

Source

open-location-code.lisp (file)

Nickname

olc

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: decode CODE

Decode an Open Location Code.

Argument CODE is an Open Location Code (a string).

Primary value is a ‘code-area’ object. Secondary value is ‘:full’ or ‘:short’ if CODE is a full or short Open Location Code respectively. If CODE is a full Open Location Code the code area denotes absolute coordinates. Otherwise, the code area denotes relative coordinates, i.e. offset values in the enclosing block.

Signal an ‘invalid-code-error’ if CODE is not a valid Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: encode LATITUDE LONGITUDE &optional PRECISION

Encode a location into an Open Location Code.

First argument LATITUDE and second argument LONGITUDE denote the location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).
Optional third argument PRECISION is the precision of the code. Default is five, i.e. a code length of ten digits.

Value is a full Open Location Code (a string).

The relation between precision, code length, and code area size is depicted in the following table.

Precision | Code Length | Width / m | Height / m ————-+————-+—————+—————
1 | 2 | 2218929.9 | 2218929.9
2 | 4 | 110946.5 | 110946.5
3 | 6 | 5547.3 | 5547.3
4 | 8 | 277.4 | 277.4
5 | 10 | 13.9 | 13.9
6 | 11 | 3.47 | 2.77
7 | 12 | 0.867 | 0.555
8 | 13 | 0.217 | 0.111
9 | 14 | 0.0542 | 0.0222
10 | 15 | 0.0135 | 0.00444

The code length is equal to the number of Open Location Code digits. Pad characters and the separator character ‘+’ are not part of the code length. The code area dimensions are calculated with a mean earth radius of 6356766 m for a code area at the equator.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: fullp CODE

True if an object is a valid full Open Location Code.

Argument CODE is an object of any type.

Value is true if CODE is a valid full Open Location Code. Otherwise, value is null.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: recover CODE LATITUDE LONGITUDE

Recover a full Open Location Code from a short code
and a reference location.

First argument CODE is an Open Location Code (a string). Second argument LATITUDE and third argument LONGITUDE denote the reference location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).

Value is the recovered full code. If CODE is already a full code, return CODE as is.

Signal an ‘invalid-code-error’ if CODE is not an Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: shorten CODE LATITUDE LONGITUDE

Remove four, six, or eight digits from the front of a full Open Location Code given a reference location.

First argument CODE is a full Open Location Code (a string). Second argument LATITUDE and third argument LONGITUDE denote the reference location in degree angle. The latitude is clipped to the closed interval [-90, 90] and the longitude is normalized to the half-closed interval [-180, 180).

Value is the short code, or the original full code if the reference location is too far.

Signal a ‘full-code-error’ if CODE is not a full Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: shortp CODE

True if an object is a valid short Open Location Code.

Argument CODE is an object of any type.

Value is true if CODE is a valid full Open Location Code. Otherwise, value is null.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: validp CODE

True if an object is a valid sequence of Open Location Code characters.

Argument CODE is an object of any type.

Value is ‘:full’ or ‘:short’ if CODE is a valid full or short Open Location Code respectively. Otherwise, value is null.

Package

open-location-code

Source

open-location-code.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: center OBJECT

Return the center latitude and longitude as multiple values.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: center (OBJECT code-area)
Generic Function: code-length OBJECT

Return the Open Location Code length.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: code-length (PRECISION integer)

Return the code length as a function of the precision.

Method: code-length (OBJECT code-area)

Return the code length of the original code.

Generic Function: north-east-corner OBJECT

Return the upper latitude and longitude as multiple values. The upper bounds are not included in the code area except for the north pole.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: north-east-corner (OBJECT code-area)
Generic Function: pad-characters OBJECT

Return the number of pad characters.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: pad-characters (OBJECT code-area)

Return the number of pad characters in the original code.

Generic Function: precision OBJECT

Return the Open Location Code precision.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: precision (LENGTH integer)

Return the precision as a function of the code length.

Method: precision (OBJECT code-area)

Return the precision of the original code.

Generic Function: separator-position OBJECT

Return the position of the separator character.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: separator-position (OBJECT code-area)

Return the position of the separator character in the original code.

Generic Function: south-west-corner OBJECT

Return the lower latitude and longitude as multiple values.

Package

open-location-code

Source

open-location-code.lisp (file)

Methods
Method: south-west-corner (OBJECT code-area)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Conditions

Condition: code-error ()

Base class for all Open Location Code errors.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

type-error (condition)

Direct subclasses
Condition: code-length-error ()

Condition for an invalid Open Location Code length.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

code-error (condition)

Condition: full-code-error ()

Condition for an invalid full Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

invalid-code-error (condition)

Condition: invalid-code-error ()

Condition for an invalid Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

code-error (condition)

Direct subclasses
Condition: short-code-error ()

Condition for an invalid short Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

invalid-code-error (condition)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Classes

Class: code-area ()

Area covered by an Open Location Code.

Package

open-location-code

Source

open-location-code.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: south

Lower latitude of the code area in degree angle.

Type

real

Initform

0

Slot: west

Lower longitude of the code area in degree angle.

Type

real

Initform

0

Slot: height

Height of the code area in degree angle.

Type

real

Initform

0

Slot: width

Width of the code area in degree angle.

Type

real

Initform

0

Slot: precision

Precision of the original code.

Type

fixnum

Initform

0

Slot: length

Code length of the original code.

Type

fixnum

Initform

0

Slot: plus

Position of the separator character in the original code.

Type

fixnum

Initform

0

Slot: pad

Number of pad characters in the original code.

Type

fixnum

Initform

0


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Constants

Constant: +alphabet+

Set of valid digits, i.e. encoding characters. The character position is equal to the decimal value, i.e. weight, of the digit.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +area-height+

Vector of code area heights in descending order. Element position is the precision of the code area.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +area-width+

Vector of code area widths in descending order. Element position is the precision of the code area.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +block-divisor+

Divisor when splitting a block into sub-blocks.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +grid-columns+

Number of grid columns.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +grid-rows+

Number of grid rows.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +maximum-length+

Maximum code length excluding the plus sign character.

Package

open-location-code

Source

open-location-code.lisp (file)

Constant: +maximum-precision+

Maximum number of discretization steps.

Package

open-location-code

Source

open-location-code.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: defconst NAME VALUE &optional DOC

Define a constant variable.

This is like ‘defconstant’ except that the initially set value is reused when the ‘defconst’ form is evaluated again.

Package

open-location-code

Source

open-location-code.lisp (file)

Macro: defsubst NAME ARG-LIST &body BODY

Define an inline function.

This is like ‘defun’ except that the function is globally marked for inline expansion by the compiler.

Package

open-location-code

Source

open-location-code.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: analyse CODE &optional AREA

Analyse an Open Location Code.

First argument CODE is the Open Location Code (an object).
If optional second argument AREA is non-null, secondary value
is a code area object.

Primary value is ‘:full’ or ‘:short’ if CODE is a valid full or short Open Location Code respectively. Otherwise, all values are null.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: area-size PRECISION

Return the height and width of a code area as multiple values.

Argument PRECISION is the number of discretization steps.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: digit VALUE

Return the digit for a decimal value.

Argument VALUE has to be a non-negative integer less than 20.

Value is the digit, i.e. encoding character.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: digitp CHAR

True if CHAR is a valid digit.

Argument CHAR has to be a character.

Value is the decimal value, i.e. weight, of the digit, or null if CHAR is an invalid digit.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: length-from-precision PRECISION

Return the code length as a function of the precision.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: normalize-location LATITUDE LONGITUDE PRECISION

Clip LATITUDE to the half-closed interval [-90, 90) and normalize LONGITUDE to the half-closed interval [-180, 180). Third argument PRECISION is used to determine the height of the code area if LATITUDE denotes the north pole.

Values are latitude, longitude, and the actual precision.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: normalize-location* LATITUDE LONGITUDE PRECISION

Like ‘normalize-location’ but return latitude and longitude as non-negative numbers.

Package

open-location-code

Source

open-location-code.lisp (file)

Function: precision-from-length LENGTH

Return the precision as a function of the code length.

Package

open-location-code

Source

open-location-code.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   O  
Index Entry  Section

F
File, Lisp, open-location-code.asd: The open-location-code<dot>asd file
File, Lisp, open-location-code/open-location-code.lisp: The open-location-code/open-location-code<dot>lisp file

L
Lisp File, open-location-code.asd: The open-location-code<dot>asd file
Lisp File, open-location-code/open-location-code.lisp: The open-location-code/open-location-code<dot>lisp file

O
open-location-code.asd: The open-location-code<dot>asd file
open-location-code/open-location-code.lisp: The open-location-code/open-location-code<dot>lisp file

Jump to:   F   L   O  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   D   E   F   G   L   M   N   P   R   S   V  
Index Entry  Section

A
analyse: Internal functions
area-size: Internal functions

C
center: Exported generic functions
center: Exported generic functions
code-length: Exported generic functions
code-length: Exported generic functions
code-length: Exported generic functions

D
decode: Exported functions
defconst: Internal macros
defsubst: Internal macros
digit: Internal functions
digitp: Internal functions

E
encode: Exported functions

F
fullp: Exported functions
Function, analyse: Internal functions
Function, area-size: Internal functions
Function, decode: Exported functions
Function, digit: Internal functions
Function, digitp: Internal functions
Function, encode: Exported functions
Function, fullp: Exported functions
Function, length-from-precision: Internal functions
Function, normalize-location: Internal functions
Function, normalize-location*: Internal functions
Function, precision-from-length: Internal functions
Function, recover: Exported functions
Function, shorten: Exported functions
Function, shortp: Exported functions
Function, validp: Exported functions

G
Generic Function, center: Exported generic functions
Generic Function, code-length: Exported generic functions
Generic Function, north-east-corner: Exported generic functions
Generic Function, pad-characters: Exported generic functions
Generic Function, precision: Exported generic functions
Generic Function, separator-position: Exported generic functions
Generic Function, south-west-corner: Exported generic functions

L
length-from-precision: Internal functions

M
Macro, defconst: Internal macros
Macro, defsubst: Internal macros
Method, center: Exported generic functions
Method, code-length: Exported generic functions
Method, code-length: Exported generic functions
Method, north-east-corner: Exported generic functions
Method, pad-characters: Exported generic functions
Method, precision: Exported generic functions
Method, precision: Exported generic functions
Method, separator-position: Exported generic functions
Method, south-west-corner: Exported generic functions

N
normalize-location: Internal functions
normalize-location*: Internal functions
north-east-corner: Exported generic functions
north-east-corner: Exported generic functions

P
pad-characters: Exported generic functions
pad-characters: Exported generic functions
precision: Exported generic functions
precision: Exported generic functions
precision: Exported generic functions
precision-from-length: Internal functions

R
recover: Exported functions

S
separator-position: Exported generic functions
separator-position: Exported generic functions
shorten: Exported functions
shortp: Exported functions
south-west-corner: Exported generic functions
south-west-corner: Exported generic functions

V
validp: Exported functions

Jump to:   A   C   D   E   F   G   L   M   N   P   R   S   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   +  
C   H   L   P   S   W  
Index Entry  Section

+
+alphabet+: Internal constants
+area-height+: Internal constants
+area-width+: Internal constants
+block-divisor+: Internal constants
+grid-columns+: Internal constants
+grid-rows+: Internal constants
+maximum-length+: Internal constants
+maximum-precision+: Internal constants

C
Constant, +alphabet+: Internal constants
Constant, +area-height+: Internal constants
Constant, +area-width+: Internal constants
Constant, +block-divisor+: Internal constants
Constant, +grid-columns+: Internal constants
Constant, +grid-rows+: Internal constants
Constant, +maximum-length+: Internal constants
Constant, +maximum-precision+: Internal constants

H
height: Exported classes

L
length: Exported classes

P
pad: Exported classes
plus: Exported classes
precision: Exported classes

S
Slot, height: Exported classes
Slot, length: Exported classes
Slot, pad: Exported classes
Slot, plus: Exported classes
Slot, precision: Exported classes
Slot, south: Exported classes
Slot, west: Exported classes
Slot, width: Exported classes
south: Exported classes

W
west: Exported classes
width: Exported classes

Jump to:   +  
C   H   L   P   S   W  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   I   O   P   S  
Index Entry  Section

C
Class, code-area: Exported classes
code-area: Exported classes
code-error: Exported conditions
code-length-error: Exported conditions
Condition, code-error: Exported conditions
Condition, code-length-error: Exported conditions
Condition, full-code-error: Exported conditions
Condition, invalid-code-error: Exported conditions
Condition, short-code-error: Exported conditions

F
full-code-error: Exported conditions

I
invalid-code-error: Exported conditions

O
open-location-code: The open-location-code system
open-location-code: The open-location-code package

P
Package, open-location-code: The open-location-code package

S
short-code-error: Exported conditions
System, open-location-code: The open-location-code system

Jump to:   C   F   I   O   P   S