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

``bash
npm install pluscodes
`

Usage

!Diagram

$3

`javascript
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+'
`

$3

`javascript
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
// }
`

$3

`javascript
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'
`

$3

`javascript
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

`typescript
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