Overview

Implementation of Open Location Codes (Plus Codes) in JavaScript/TypeScript with full support for 2-15 digit precision.

See a description with running code at Runkit.

Features

• Encode coordinates to Plus Codes (2-15 digits)
• Decode Plus Codes to coordinates
• Shorten codes relative to a reference location
• Expand shortened codes
• Full TypeScript support with type definitions
• Zero dependencies
• Matches Google's reference implementation

Installation

npm install pluscodes

Usage

Encoding

const { encode } = require('pluscodes')

// Default 10-digit code (~14m × 14m precision)
encode({ latitude: 59.332438, longitude: 18.118813 }) // '9FFW84J9+XG'

// Custom precision (2-15 digits supported)
encode({ latitude: 59.332483, longitude: 18.118765 }, 11) // '9FFW84J9+XGR'  (3m × 3m)
encode({ latitude: 59.332483, longitude: 18.118765 }, 12) // '9FFW84J9+XGR7' (56cm × 87cm)
encode({ latitude: 59.332483, longitude: 18.118765 }, 15) // '9FFW84J9+XGR7Q44' (4mm × 14mm)

// Lower precision codes
encode({ latitude: 59.332438, longitude: 18.118813 }, 8) // '9FFW84J9+'
encode({ latitude: 59.332438, longitude: 18.118813 }, 4) // '9FFW0000+'

Decoding

const { decode } = require('pluscodes')

decode('9FFW84J9+XG')
// {
//   latitude: 59.332438,
//   longitude: 18.118813,
//   latitudeResolution: 0.000125,
//   longitudeResolution: 0.000125
// }

decode('9FFW84J9+XGR7Q44')
// {
//   latitude: 59.332483,
//   longitude: 18.118765,
//   latitudeResolution: 4e-8,
//   longitudeResolution: 1.2207031e-7
// }

Shortening codes

const { shorten } = require('pluscodes')
shorten('9FFW84J9+XG', { latitude: 59.329394, longitude: -162.068712 }) // '9FFW84J9+XG'
shorten('9FFW84J9+XG', { latitude: 59.329394, longitude: 18.068712 }) // '84J9+XG'
shorten('9FFW84J9+XG', { latitude: 59.332438, longitude: 18.118813 }) // 'J9+XG'

Expanding short codes

const { expand } = require('pluscodes')
expand('FW84J9+XG', { latitude: 59.329394, longitude: 18.068712 }) // '9FFW84J9+XG'
expand('84J9+XG', { latitude: 59.329394, longitude: 18.068712 }) // '9FFW84J9+XG'
expand('J9+XG', { latitude: 59.329394, longitude: 18.068712 }) // '9FFW83J9+XG'

Code Precision

Digits	Precision (lat × lon)	Example Use Case
2	20° × 20°	Country
4	1° × 1°	Large city
6	0.05° × 0.05°	District
8	0.0025° × 0.0025°	Neighborhood
10	0.000125° × 0.000125° (~14m × 14m)	Building (default)
11	25µ° × 31.25µ° (~3m × 3m)	Building entrance
12	5µ° × 7.8µ° (~56cm × 87cm)	Room
13	1µ° × 2µ° (~11cm × 22cm)	Table
14	0.2µ° × 0.5µ° (~2cm × 5cm)	Chair
15	0.04µ° × 0.12µ° (~4mm × 14mm)	Precision object

TypeScript Support

import { encode, decode, type Coordinates, type DecodedLocation } from 'pluscodes'

const coords: Coordinates = {
  latitude: 59.332483,
  longitude: 18.118765
}

const code = encode(coords, 11) // '9FFW84J9+XGR'
const location: DecodedLocation = decode(code)

Author

Jan Andersson, jan.andersson@gmail.com