open-location-code/API.txt

Open Location Codes are a way of encoding location into a form that is easier to use than latitude and longitude. Source for a website to demonstrate Open Location Codes. (https://github.com/google/open-location-code)

Open Location Code API Reference

The following public methods should be provided by any Open Location Code
implementation, subject to minor changes caused by language conventions.

Note that any method that returns an Open Location Code should return
upper case characters, with the prefix, and full codes should include
a separator if they have five or more characters.

Methods that accept Open Location Codes as parameters should be case
insensitive, prefixes optional, and for full codes the separator character
is optional (although if present, it is permissable to throw an error if
there are more than one or if it is in the wrong position).

isValid:
  The isValid method takes a single parameter, a string, and returns a
  boolean indicating whether the string is a valid Open Location Code
  sequence or not.

  To be valid, all characters must be from the Open Location Code character
  set with at most one separator. If the separator character is present, it
  must be after four characters. If the prefix character is present, it must
  be the first character.

isShort:
  The isShort method takes a single parameter, a string, and returns a
  boolean indicating whether the string is a valid short Open Location Code
  or not.

  A short Open Location Code is a sequence created by removing the first
  four or six characters from a full Open Location Code.

  A code must be a possible sub-string of a generated Open Location Code, at
  least four and at most seven characters long and not include a separator
  character. If the prefix character is present, it must be the first
  character.

isFull:
  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. If the prefix
  character is present, it must be the first character. If the separator
  character is present, it must be after four characters.

encode:
    Encode a location into an Open Location Code. This takes a latitude and
    longitude and an optional length. If the length is not specified, a code
    with 10 characters (excluding the prefix and separator) will be generated.

decode:
    Decodes an Open Location Code into the location coordinates. This method
    takes a string. If the string is a valid full Open Location Code, it
    returns an object with the lower and upper latitude and longitude pairs,
    the center latitude and longitude, and the length of the original code.

shortenBy4:
    Passed a valid full 10 or 11 character Open Location Code and a latitude
    and longitude, this tries to remove the first four characters. This will
    only succeed if both the latitude and longitude are less than 0.25
    degrees from the code center. (Up to 0.5 degrees difference would work,
    the requirement for 0.25 degrees represents a safety margin for cases
    where the coordinates have come from a geocoding system and where the
    center of large entities, such as cities, is subject to debate.)

    If not possible, the original code is returned. If trimming is possible,
    the first four characters are removed and the subsequent characters are
    returned with the prefix added.

shortenBy6:
    Passed a valid full 10 or 11 character Open Location Code and a latitude
    and longitude, this tries to remove the first six characters. This will
    only succeed if both the latitude and longitude are less than 0.0125
    degrees from the code center. (Up to 0.025 degrees difference would
    work, the requirement for 0.0125 degrees represents a safety margin for
    cases where the coordinates have come from a geocoding system and where
    the center of large entities, such as cities, is subject to debate.)

    If not possible, the original code is returned. If trimming is possible,
    the first six characters are removed and the subsequent characters are
    returned with the prefix added.

recoverNearest:
    This method is passed a valid short Open Location Code (of four to seven
    characters) and a latitude and longitude, and returns the nearest
    matching full Open Location Code to the specified location.

    The number of characters that will be prepended to the short code, where S
    is the supplied short code and R are the computed characters, are:
    SSSS    -> RRRR.RRSSSS
    SSSSS   -> RRRR.RRSSSSS
    SSSSSS  -> RRRR.SSSSSS
    SSSSSSS -> RRRR.SSSSSSS
    Note that short codes with an odd number of characters will have their
    last character decoded using the grid refinement algorithm.