pidf-lo - PIDF-LO and GEOPRIV handling

This library should simplify handling PIDF-LO GEOPRIV documents as described in https://tools.ietf.org/html/rfc5491.

This README currently only describes simple usage of this library. More elaborate implementation examples will be added by time.

Important Notices

This implemenentation only covers a small portion of the PIDF-LO specification documents and is (by far) not complete. Pull requests are therefore highly honored.

This library requires @xmldom/xmldom as a peer-dependency only in node.js environments! JavaScript browser environments always have a DOM implementation on board, therefore @xmldom/xmldom is not needed there.

Installation

Requires node.js and npm.

npm install pidf-lo

Simplified Usage (WGS84 locations)

PIDF-LO creation

import { 
  LocationMethod, 
  PidfLo, 
  XMLCompat,

  getNodeImpl,
  getWebImpl,
} from 'pidf-lo';

// if xmldom interface is available (e.g. on web browsers)
XMLCompat.initialize(getNodeImpl());
// if xmldom interface is NOT available (e.g. on node environments)
// also don't forget to install required peer dependency @xmldom/xmldom
XMLCompat.initialize(getWebImpl());

const pidf = PidfLo.fromSimpleLocation({
  latitude: 48.123,
  longitude: 14.456,
  radius: 24,
  method: LocationMethod.GPS,
});

if (!pidf)
  throw 'Something is wrong with this location';

const xmlObj = pidf.toXML();
console.log(XMLCompat.toXMLString(xmlObj));

PIDF-LO parsing

import { 
  PidfLo, 
  XMLCompat,

  getNodeImpl,
  getWebImpl,
} from 'pidf-lo';

// if xmldom interface is available (e.g. on web browsers)
XMLCompat.initialize(getNodeImpl());
// if xmldom interface is NOT available (e.g. on node environments)
// also don't forget to install required peer dependency @xmldom/xmldom
XMLCompat.initialize(getWebImpl());

const parsed = PidfLo.fromXML('<xml...>');

if (!parsed || !parsed.simple)
  throw 'Something is wrong with this location';

const simpleLoc = parsed.simple;
console.log(`${simpleLoc.latitude} ${simpleLoc.longitude}`);

Usage (Civic Addresses)

PIDF-LO creation

import { 
  LocationMethod, 
  PidfLo, 

  getNodeImpl,
  getWebImpl,
} from 'pidf-lo';

// if xmldom interface is available (e.g. on web browsers)
XMLCompat.initialize(getNodeImpl());
// if xmldom interface is NOT available (e.g. on node environments)
// also don't forget to install required peer dependency @xmldom/xmldom
XMLCompat.initialize(getWebImpl());

const pidf = PidfLo.fromSimpleLocation({
  civic: {
    country: 'AT',
    A1: 'Upper Austria',
    A4: 'Schärding',
    FLR: '5',
    PC: '4780',
    NAM: 'Hospital',
  },
  method: LocationMethod['AP-802.11'],
}, 'lkh-schaerding.at');

if (!pidf)
  throw 'Something is wrong with this location';

const xmlObj = pidf.toXML();
console.log(XMLCompat.toXMLString(xmlObj));

PIDF-LO parsing

import { 
  PidfLo,

  getNodeImpl,
  getWebImpl,
} from 'pidf-lo';

// if xmldom interface is available (e.g. on web browsers)
XMLCompat.initialize(getNodeImpl());
// if xmldom interface is NOT available (e.g. on node environments)
// also don't forget to install required peer dependency @xmldom/xmldom
XMLCompat.initialize(getWebImpl());

const parsed = PidfLo.fromXML('<xml...>');

if (!parsed || !parsed.simple || !parsed.simple.civic)
  throw 'Something is wrong with this location';

const simpleCivic = parsed.simple.civic;
console.log(`${simpleCivic.country} ${simpleCivic.A1}`);

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

Distributed under the MIT License. See LICENSE for more information.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.3.0] - 2024-04-04

Added

• Parsing of timestamp strings for simple locations.

[1.2.1] - 2023-11-28

Fixed

• Transform circles with radius <1 meter as points.

[1.2.0]

Added

• New interface for simpleArray.

Fixed

• Avoid multiprocessing of simple locations.
• Process all location info elements.

[1.1.0]

Added

• Support multiple simple locations.

[1.0.2] - 2023-05-05

Fixed

• Removed dm namespace for tuples as this is incorrect. The namespace should only be used for Person and Device.