@webkitty/geo-rev

GEO:Rev

🌐 stuchl4n3k.net | 💻 stuchl4n3k | 🐦 @stuchl4n3k

Simple reverse geocoder for Node.js that works with offline data and offers fast lookup times.
📍 → 🌐🔍 → 🏘️

Every release of the package contains a modified version of the latest free GeoNames.org cities500 dataset (licensed under a Creative Commons Attribution 4.0 License). There is also a possibility to use an external dataset in the same format. Geocoding of given coordinates is performed using a K-D Tree index, which is built during initialization of the component.

✅ Features

• Parses local (offline) geographical database of places.
• Looks up a nearest place (town/city) to a given geographical location.

⚙️ Usage

Show me the code!

import { createRevGeocoder } from '@webkitty/geo-rev';

const revGeocoder = await createRevGeocoder();
const result = revGeocoder.lookup({latitude: 50.652576, longitude: 13.723918});
console.log(result);

{
  record: {
    name: 'Hrob',
    latitude: 50.65919,
    longitude: 13.72676,
    countryCode: 'CZ'
  },
  distance: 0.7622437751065233  // [km]
}

By default the geocoder uses a bundled dataset.

OK, what if I need to update the dataset in the future?

The latest dataset is bundled with each release, but you can always supply yours:

const revGeocoder = await createRevGeocoder({dataset: '/path/to/your/dataset.csv'});

We use a simple script to convert the GeoNames.org dataset to the supported format:

wget https://download.geonames.org/export/dump/cities500.zip -O /tmp/geonames.zip
unzip /tmp/geonames.zip | cut -f2,5,6,9 -s --output-delimiter=';' > cities500.csv

But I have a custom dataset!

No problem, I can hear you. Just convert yours to the following format:

• Cell delimiter is a semi-colon (;).
• Row delimiter is a Unix LF (\n).
• There is no header row.
• Cell values are not quoted.
• Order of the columns is:
  1. Name of the place (UTF8 string)
  2. Latitude (float number)
  3. Longitude (float number)
  4. ISO Alpha-2 country code of the place (string)

For the sake of completeness the CSV should look as follows:

Soldeu;42.57688;1.66769;AD
Musashino;35.70611;139.55944;JP
Ängelholm;56.2428;12.86219;SE
...

🛠️ Build

make

🙇‍ Dependencies and attributions

• https://github.com/mikolalysenko/static-kdtree - Static K-D tree data structure
• https://geonames.org - The GeoNames geographical database

📜 License

Copyright © 2020 stuchl4n3k. This project is MIT licensed.