- Location
Location utility class. Acts as an abstraction for everything we need to know about a location:
- Fetching it from the Geolocation API
- Initialising it from OLC codes, OS Grid ref, or lan/lon
- Querying it as long or short OLC codes, OSGR or lat/lon
- Generating a short OLC code by referencing the internal places database in places.json
Many of these functions could be performed more succinctly by calling external services, but this class was developed for use in an application which needs to run in an environment where there may be no connectivity. The only dependency is on places.json in the current source tree.
- Position :
Object - plusCodeString :
String A full 10 or 11 digit OLC (plus code) string
- shortPlusCodeString :
String The least significant digits of a plus code which are relative to a reference point, followed by
comma,spaceand the name of the reference point.- OSGRString :
String An OS grid reference in human readable form: 3, 4, or 5 digit reference, two upper case alphabetics followed by two groups of 3, 4, or 5 digits.
- plusCode :
Object Object representing a parsed long or short OLC plusCode
- OSGridRef :
Object Object representing a parsed OS grid reference
Location utility class. Acts as an abstraction for everything we need to know about a location:
- Fetching it from the Geolocation API
- Initialising it from OLC codes, OS Grid ref, or lan/lon
- Querying it as long or short OLC codes, OSGR or lat/lon
- Generating a short OLC code by referencing the internal places database in places.json
Many of these functions could be performed more succinctly by calling external services, but this class was developed for use in an application which needs to run in an environment where there may be no connectivity. The only dependency is on places.json in the current source tree.
Kind: global class
- Location
- new Location([location])
- instance
- .isValid :
boolean - .latitude :
number - .longitude :
number - .accuracy :
number - .plusCode :
plusCodeString - .shortCode :
shortPlusCodeString - .phoneticCode :
String - .osGridRef :
OSGRString - .queryDevice() ⇒
Promise - .shortCodes([num]) ⇒
Array.<shortPlusCodeString> - .phoneticCodes([num]) ⇒
Array.<String>
- .isValid :
- static
- .parseLocationString(input) ⇒
plusCode|OSGridRef - .autoComplete(input) ⇒
Array.<String>
- .parseLocationString(input) ⇒
Creates an instance of Location. It can either be created as an un-initialised container, in which case a later call on the queryDevice() method is used to populate it with the device location from the geolocation API, or we can instantiate it with various forms of location anchor:
- latitude, longitude, altitude, accuracy: Decimal degrees of position using WGS84 (GPS) Datum
- Full Open Location Code
- Short Location Code, with placename reference
- OS Grid Reference 3, 4, or 5 digit reference in the form "NY 12345 67890"
Once set, Locations are immutable by design, there is no "set" or "update" method. This may or may not be a good design decision. In particular, there are use cases where the location should track a moving device.
| Param | Type | Description |
|---|---|---|
| [location] | Position | plusCodeString | shortPlusCodeString | OSGRString |
If passed then the new location instance will be initialised to these coordinates. |
Has this instance been initialised with a valid location?
Kind: instance property of Location
Read only: true
Latitude of represented location
Kind: instance property of Location
Read only: true
Longitude of represented location
Kind: instance property of Location
Read only: true
The radius of uncertainty for the location, or zero if unknown or unsupported.
Currently only supported for values obtained using #queryDevice
Kind: instance property of Location
Read only: true
location.plusCode : plusCodeString
Kind: instance property of Location
Read only: true
location.shortCode : shortPlusCodeString
Kind: instance property of Location
Read only: true
shortCode, transcribed into a string using the NATO phonetic alphabet
for alpha characters and the English word spelling for digits and the + sign.
Kind: instance property of Location
Read only: true
location.osGridRef : OSGRString
The OS Grid ref in conventional (two alpha tile prefix) format
Kind: instance property of Location
Read only: true
Query the GeoLocation API on the current device and initialise the internal representation if successful.
Kind: instance method of Location
Returns: Promise - Resolves when location is retrieved from device
rejects on error.
Fulfill: Position
Reject: Error
location.shortCodes([num]) ⇒ Array.<shortPlusCodeString>
A list of possible short OLC codes that are valid for this location, typically sorted in a sensible order:
- shortest codes first
- within codes of same length, nearest location references
- nearest large location (e.g. City)
Kind: instance method of Location
| Param | Type | Default | Description |
|---|---|---|---|
| [num] | number |
5 |
Maximum number of results to return |
List of possible short OLC codes spelt out phonetically Identical to shortCodes, but alpabetic characters are mapped onto NATO phonetic alphabet
Kind: instance method of Location
| Param | Type | Default |
|---|---|---|
| [num] | number |
5 |
Takes an input string and tries to determine what format it is in and then parse it to provide a complete or partial location.
Currently handles OLC codes and OS grid references, should extend this to include literal lat/lon.
Kind: static method of Location
| Param | Type |
|---|---|
| input | plusCodeString | shortPlusCodeString | OSGRString |
Takes a textual input and generates an array of possible completions, at present targets only OLC shortened plus codes, where the completions are possible reference placenames.
Kind: static method of Location
Returns: Array.<String> - An array of possible completions
| Param | Type | Description |
|---|---|---|
| input | String |
A partial location |
Kind: global typedef
Properties
| Name | Type | Description |
|---|---|---|
| latitude | number |
Decimal degrees of latitude |
| longitude | number |
Decimal degrees of longitude |
| altitude | number |
Altitude above mean sea level in metres |
| accuracy | number |
The radius of uncertainty for of the location. |
A full 10 or 11 digit OLC (plus code) string
Kind: global typedef
Example
85GCQ2XF+C84Example
85GCQ2XF+C8The least significant digits of a plus code which are relative to a
reference point, followed by comma, space and the name of the reference point.
Kind: global typedef
Example
G8+7GV, Hoxton, EnglandAn OS grid reference in human readable form: 3, 4, or 5 digit reference, two upper case alphabetics followed by two groups of 3, 4, or 5 digits.
Kind: global typedef
Example
NY 12345 67890Example
ST123456Object representing a parsed long or short OLC plusCode
Kind: global typedef
Properties
| Name | Type | Description |
|---|---|---|
| plusCode | String |
The full or short pluscode |
| separator | String |
The separator between the plusCode and any trailing placename (usually ", ") |
| placeName | String |
The placename in the input |
| places | String |
Places in the internal names database which match placeName |
Object representing a parsed OS grid reference
Kind: global typedef
Properties
| Name | Type |
|---|---|
| easting | number |
| northing | number |