Home

Awesome

nostr-geotags

opensats.org semver cov test publish docs covgen npm bundle size npm bundle size

Summary

nostr-geotags is a modern ESM-only package for generating discoverable geohash and ISO-3166-1/2/3 tags using NIP_32 based on various inputs like latitude, longitude, city, country, etc. It uses iso-3166 and ngeohash to generate geodata. This package is alpha and the API and response formats will change. This package has gone full-circle and now implements NIP-32 just as it did in the first commit.

This package was derived from needs in @nostrwatch, an OpenSats Grant Recipient, and so was made possible by OpenSats.

Installation

The package is available on npm and can be installed using npm, yarn, or pnpm.

npm install nostr-geotags

yarn add nostr-geotags

pnpm add nostr-geotags

Usage

import ngeotags from 'nostr-geotags'

event = {}
event.kind = 1
//created_at, content etc...
event.tags = []
event.tags.push(['t', 'nostrworks'])

const inputData = {
  lat: 52.5200,
  lon: 13.4050,
  city: 'Berlin',
  countryCode: 'DE'
};

const options = {
  geohash: true,
  gps: true,
  city: true,
  iso31662: true
};

event.tags = [...event.tags, ...ngeotags(inputData, options)];
//sign and verify the event
console.log(event);

Input Reference

The inputData object can contain:

Input Reference

The inputData object can contain the following properties, used to generate geo-tags:

Options Reference

The options object specifies which types of tags to generate.

ISO options

Response Options

Please note: that these will only have an effect on the output if the input for their corresponding values were set. This is especially true for passthrough values. Some of these passthrough values may be deduped if they are not unique against ISO values.

Response Reference

The function returns an array of tuples, where each tuple represents a tag and its associated data. The format of the tuples is based on NIP-01.

Determining tag usage

Which tags you use depend on use-case. If your concerns are namely geospacial, using only geohashes likely suffice, if your concerns around around borders, languages or laws, ISO-3166-3 may suffice. If your concerns are mixed, a combination of standards will suffice. In most cases the defaults are good, and most likely won't need to be changed unless you are optimizing your tags array.

Tag Types and Their Descriptions

  1. GPS: [ 'g', '<latitude>, <longitude>', 'dd' ], [ 'g', '<latitude>', 'lat' ] and [ l', '<longitude>', 'lon' ]

    • Coordinates of diminishing resolution from the input latitude and longitude. One of each of these tags are passthrough, but the rest are progressively reduced in their precision until the final decimal point. If an integer is provided for one or both lat and lon, an integer is returned.

  2. Geohash: [ g', '<geohash>'] (NIP-52)

    • Geohashes of diminishing resolution from the input latitude and longitude. These are not passthrough; they are computed using the ngeohash library.

  3. ISO-3166-1 Codes:

    • These tags represent country information derived from the iso-3166 library and are based on the provided countryCode input value. They are not passthrough.
    • Examples
    • isoAsNamespace==false [default]
      • Alpha-2 code: [ 'l', 'HU', 'ISO-3166-1' ]
      • Alpha-3 code: [ 'l', 'HUN', 'ISO-3166-1']
      • Numeric code: [ 'l', '348', 'ISO-3166-1']

  4. ISO-3166-2 Codes:

    • These tags represent region information derived from the iso-3166 library and are based on the countryCode and regionCode input values. They are not passthrough values.

  5. ISO-3166-3 Codes:

    • These tags also represent country information, but focus on historical changes in country codes. They are not passthrough.
    • Examples mirror the ISO-3166-1 format but relate to updated country codes.

  6. City: [ 'g', 'Budapest', 'cityName' ]

    • A passthrough from the input city name.

  7. Planet: [ 'g', 'Earth', 'planetName' ]

    • A passthrough, assuming Earth as the default planet in the absence of specific planetary data.

ISO-3166-3 Behaviors

When iso31663 is enabled, it will affect the response contents. Any ISO-3166-3 code found for a given ISO-3166-1 countryCode that is not a duplicate of it's ISO-3166-1 counterpart, will be appended to the tags array. Here's an example:

[ [ 'L', 'ISO-3166-1' ], [ 'g', 'AI', 'ISO-3166-1'], [ 'g', 'AIA', 'ISO-3166-1' ], [ 'g', '660', 'ISO-3166-1'], [ 'G', 'ISO-3166-3' ], [ 'g', 'DJ', 'ISO-3166-3' ], [ 'G', 'countryName' ], [ 'g', 'Anguilla', 'countryName' ] ]

Here two alpha2 codes are returned, the original ISO-3166-1 code, and the changed ISO-3166-3 code. Since the other ISO-3166-3 properties for AI are the same as their ISO-3166-1 counter-parts, they are not included.

Example Response

Here is the default response when lat, lon, countryCode, regionName, and planet are provided, with everything else default

[ 'g', 'u2mwdd8q4' ],
[ 'g', 'u2mwdd8q' ],
[ 'g', 'u2mwdd8' ],
[ 'g', 'u2mwdd' ],
[ 'g', 'u2mwd' ],
[ 'g', 'u2mw' ],
[ 'g', 'u2m' ],
[ 'g', 'u2' ],
[ 'g', 'u' ],
[ 'L', 'countryCode' ],
[ 'l', 'HU', 'countryCode' ],
[ 'l', 'HUN', 'countryCode' ],
[ 'l', '348', 'countryCode' ],
[ 'L', 'countryName' ],
[ 'l', 'Hungary', 'countryName' ],
[ 'L', 'cityName' ],
[ 'l', 'Budapest', 'cityName' ]

This is a response with all options enabled (deduped, dedupe: true)

[ 'g', 'u2mwdd8q4' ],
[ 'g', 'u2mwdd8q' ],
[ 'g', 'u2mwdd8' ],
[ 'g', 'u2mwdd' ],
[ 'g', 'u2mwd' ],
[ 'g', 'u2mw' ],
[ 'g', 'u2m' ],
[ 'g', 'u2' ],
[ 'g', 'u' ],
[ 'l', '47.5636, 19.0947', 'dd' ],
[ 'L', 'dd.lat' ],
[ 'l', '47.5636', 'dd.lat' ],
[ 'l', '47.563', 'dd.lat' ],
[ 'l', '47.56', 'dd.lat' ],
[ 'l', '47.5', 'dd.lat' ],
[ 'L', 'dd.lon' ],
[ 'l', '19.0947', 'dd.lon' ],
[ 'l', '19.094', 'dd.lon' ],
[ 'l', '19.09', 'dd.lon' ],
[ 'l', '19', 'dd.lon' ],
[ 'L', 'countryCode' ],
[ 'l', 'HU', 'countryCode' ],
[ 'l', 'HUN', 'countryCode' ],
[ 'l', '348', 'countryCode' ],
[ 'L', 'countryName' ],
[ 'l', 'Hungary', 'countryName' ],
[ 'L', 'regionCode' ],
[ 'l', 'HU-BU', 'regionCode' ],
[ 'L', 'cityName' ],
[ 'l', 'Budapest', 'cityName' ],
[ 'L', 'planetName' ],
[ 'l', 'Earth', 'planetName' ]

Development

To build the package, run:

npm run build

To run tests:

npm test