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 1.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 14:41:57 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

1.0

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 a short 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.

Signal a ‘short-code-error’ if CODE is not a short 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

open-location-code::float-type

Initform

0.0d0

Slot: west

Lower longitude of the code area in degree angle.

Type

open-location-code::float-type

Initform

0.0d0

Slot: height

Height of the code area in degree angle.

Type

open-location-code::float-type

Initform

0.0d0

Slot: width

Width of the code area in degree angle.

Type

open-location-code::float-type

Initform

0.0d0

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: +float-type+

Data type for floating-point numbers.

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)


Next: , 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: fix NUMBER DIVISOR

Round NUMBER to the nearest multiple of DIVISOR.

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: Internal definitions   [Contents][Index]

5.2.4 Types

Type: float-type &rest SPEC

Type specifier for floating-point numbers.

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
fix: Internal functions
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, fix: Internal 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
+float-type+: 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, +float-type+: 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   T  
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
float-type: Internal types
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

T
Type, float-type: Internal types

Jump to:   C   F   I   O   P   S   T