Pluscode (Pluscode v0.1.0)
View SourceConvert locations to and from Open Location Codes (Plus Codes).
Plus Codes are short, 10-11 character codes that can be used instead of street addresses. The codes can be generated and decoded offline, and use a reduced character set that minimizes the chance of codes including words.
Codes are able to be shortened relative to a nearby location. This means that in many cases, only four to seven characters of the code are needed. To recover the original code, the same location is not required, as long as a nearby location is provided.
Codes represent rectangular areas rather than points, and the longer the code, the smaller the area. A 10 character code represents a 13.5x13.5 meter area (at the equator). An 11 character code represents approximately a 2.8x3.5 meter area.
Summary
Functions
A struct representing the coordinates of a decoded Open Location Code.
Compute the latitude precision value for a given code length.
Decodes an Open Location Code into the location coordinates. Returns a Pluscode struct that includes the coordinates of the bounding box - the lower left, center and upper right. Args: code: The Open Location Code to decode. Returns: A Pluscode struct that provides the latitude and longitude of two of the corners of the area, the center, and the length of the original code.
Encode a location into an Open Location Code.
Determines if a code is a valid full Open Location Code.
Normalize a longitude into the range -180 to 180, not including 180.
Recover the nearest matching code to a specified location. Recover the nearest matching full code to a specified location.
Determines if a code is a valid short code.
Remove characters from the start of an Open Location Code.
Determines if a code is valid.
Types
Functions
A struct representing the coordinates of a decoded Open Location Code.
The coordinates include the latitude and longitude of the lower left and upper right corners and the center of the bounding box for the area the code represents.
Fields
:latitude_lo
- The latitude of the SW corner in degrees.:longitude_lo
- The longitude of the SW corner in degrees.:latitude_hi
- The latitude of the NE corner in degrees.:longitude_hi
- The longitude of the NE corner in degrees.:latitude_center
- The latitude of the center in degrees.:longitude_center
- The longitude of the center in degrees.:code_length
- The number of significant characters that were in the code (excluding separator).
Compute the latitude precision value for a given code length.
Args
code_length
- The length of the code to compute precision for.
Returns
The precision value in degrees. For lengths <= 10, latitude and longitude have the same precision. For lengths > 10, latitude has a different precision due to the grid method having fewer columns than rows.
Examples
iex> Pluscode.compute_latitude_precision(10)
0.000125
iex> Pluscode.compute_latitude_precision(11)
2.5e-5
Decodes an Open Location Code into the location coordinates. Returns a Pluscode struct that includes the coordinates of the bounding box - the lower left, center and upper right. Args: code: The Open Location Code to decode. Returns: A Pluscode struct that provides the latitude and longitude of two of the corners of the area, the center, and the length of the original code.
Encode a location into an Open Location Code.
Args
latitude
- The latitude in signed decimal degrees. Must be between -90 and 90.longitude
- The longitude in signed decimal degrees. Must be between -180 and 180.code_length
- The number of significant digits in the output code (default: 10).The length determines the precision of the code.
Returns
A string containing the Open Location Code.
Examples
iex> Pluscode.encode(47.365590, 8.524997)
"8FVC9G8F+6X"
iex> Pluscode.encode(47.365590, 8.524997, 11)
"8FVC9G8F+6XQ"
Determines if a code is a valid full Open Location Code.
Not all possible combinations of Open Location Code characters decode to valid latitude and longitude values. This checks that a code is valid and also that the latitude and longitude values are legal.
Args
code
- The code to check.
Returns
true
if the code is a valid full code, false
otherwise.
Rules
- If the prefix character is present, it must be the first character.
- If the separator character is present, it must be after four characters.
- The first latitude character must decode to a valid latitude (<90 degrees).
- The first longitude character must decode to a valid longitude (<180 degrees).
Examples
iex> Pluscode.full?("8FVC9G8F+6X")
true
iex> Pluscode.full?("9G8F+6X")
false
Normalize a longitude into the range -180 to 180, not including 180.
Args
longitude
- A longitude in signed decimal degrees.
Returns
The normalized longitude value.
Examples
iex> Pluscode.normalize_longitude(185)
-175
iex> Pluscode.normalize_longitude(-185)
175
Recover the nearest matching code to a specified location. Recover the nearest matching full code to a specified location.
Given a short code of between four and seven characters, this recovers the nearest matching full code to the specified location.
Args
code
- A valid short Open Location Code.reference_latitude
- The reference latitude in signed decimal degrees.reference_longitude
- The reference longitude in signed decimal degrees.
Returns
A string containing the nearest matching full Open Location Code.
Examples
iex> Pluscode.recover_nearest("9G8F+6X", 47.4, 8.6)
"8FVC9G8F+6X"
Determines if a code is a valid short code.
A short Open Location Code is a sequence created by removing four or more digits from an Open Location Code. It must include a separator character.
Args
code
- The code to check.
Returns
true
if the code is a valid short code, false
otherwise.
Examples
iex> Pluscode.short?("9G8F+6X")
true
iex> Pluscode.short?("8FVC9G8F+6X")
false
Remove characters from the start of an Open Location Code.
This uses a reference location to determine how many initial characters can be removed from the OLC code. The number of characters that can be removed depends on the distance between the code center and the reference location.
Args
code
- A full Open Location Code to shorten.latitude
- The reference latitude in signed decimal degrees.longitude
- The reference longitude in signed decimal degrees.
Returns
A string containing the shortened Open Location Code.
Rules
- The minimum number of characters that will be removed is four.
- If more than four characters can be removed, the additional characters will be replaced with the padding character (0).
- At most eight characters will be removed.
- The reference location must be within 50% of the maximum range.
Examples
iex> Pluscode.shorten("8FVC9G8F+6X", 47.5, 8.5)
"9G8F+6X"
Determines if a code is valid.
To be valid, all characters must be from the Open Location Code character set with at most one separator. The separator can be in any even-numbered position up to the eighth digit.
Args
code
- The code to validate.
Returns
true
if the code is valid, false
otherwise.
Examples
iex> Pluscode.valid?("8FVC9G8F+6X")
true
iex> Pluscode.valid?("8FVC9G8F+")
true
iex> Pluscode.valid?("invalid")
false