Pluscodes

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