Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Open Location Code JavaScript API

This is the JavaScript implementation of the Open Location Code API.

The library file is in src/openlocationcode.js. There is also a minified version, and both are also available using the following CDNs:

Unit tests are included and can be executed by installing gulp, gulp-qunit and gulp-util and running gulp. Unit tests are automatically run on pull and push requests and visible at https://travis-ci.org/google/open-location-code.

Example web pages illustrating converting map clicks to Open Location Codes, and using Googles Maps API to extend place codes to full codes are in the examples/ directory.

More examples are on jsfiddle.

Public Methods

The following are the four public methods and one object you should use. All the other methods in the code should be regarded as private and not called.

encode()

OpenLocationCode.encode(latitude, longitude, codeLength) → {string}

Encode a location into an Open Location Code.

Parameters:

Name Type Description
latitude number The latitude in signed decimal degrees. Values less than -90 will be clipped to -90, values over 90 will be clipped to 90.
longitude number The longitude in signed decimal degrees. This will be normalised to the range -180 to 180.
codeLength number The desired code length. If omitted, OpenLocationCode.CODE_PRECISION_NORMAL will be used. For precision OpenLocationCode.CODE_PRECISION_EXTRA is recommended.

Returns:

The code for the location.

Exceptions:

If any of the passed values are not numbers, an exception will be thrown.

decode()

OpenLocationCode.decode(code) → {OpenLocationCode.CodeArea}

Decodes an Open Location Code into its location coordinates.

Parameters:

Name Type Description
code string The code to decode.

Returns:

The OpenLocationCode.CodeArea object.

Exceptions:

If the passed code is not a valid full code, an exception will be thrown.

shorten()

OpenLocationCode.shorten(code, latitude, longitude) → {string}

Remove characters from the start of an OLC 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.

Parameters:

Name Type Description
code string The code to shorten.
latitude number The latitude of the reference location.
longitude number The longitude of the reference location.

Returns:

The code, shortened as much as possible that it is still the closest matching code to the reference location.

Exceptions:

If the code is not a valid full code, or the latitude or longitude are not numbers, an exception will be thrown.

recoverNearest()

OpenLocationCode.recoverNearest(shortCode, referenceLatitude, referenceLongitude) → {string}

Recover the nearest matching code to a specified location.

This is the counterpart to OpenLocationCode.shorten(). This recovers the nearest matching full code to the reference location.

Parameters:

Name Type Description
shortCode string The code to recover.
referenceLatitude number The latitude of the reference location.
referenceLongitude number The longitude of the reference location.

Returns:

The nearest matching full code to the reference location.

Exceptions:

If the short code is not valid, or the reference position values are not numbers, an exception will be thrown.

CodeArea

OpenLocationCode.CodeArea(latitudeLo, longitudeLo, latitudeHi, longitudeHi, codeLength) → {OpenLocationCode.CodeAre}

The OpenLocationCode.CodeArea class is used to return the area represented by a code. Because codes are areas, not points, this gives the coordinates of the south-west and north-east corners, the center, and the length of the code.

You can convert from a code to an area and back again like this:

var a = '796RWF8Q+WF';
var area = OpenLocationCode.decode(a);
var original_code = OpenLocationCode.encode(area.latitudeCenter, area.longitudeCenter, area.codeLength);

Attributes:

Name Type Description
latitudeLo number The latitude of the south-west corner.
longitudeLo number The longitude of the south-west corner.
latitudeHi number The latitude of the north-east corner.
longitudeHi number The longitude of the north-east corner.
latitudeCenter number The latitude of the center.
longitudeCenter number The longitude of the center.
codeLength number The length of the code that generated this area.