TypeScript icon, indicating that this package has built-in type declarations

    1.1.1 • Public • Published


    🌐 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.


    • [x] Parses local (offline) geographical database of places.
    • [x] 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});
      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:


    🛠️ Build


    🙇‍ Dependencies and attributions

    📜 License

    Copyright © 2020 stuchl4n3k. This project is MIT licensed.


    npm i @webkitty/geo-rev

    DownloadsWeekly Downloads






    Unpacked Size

    6.29 MB

    Total Files


    Last publish


    • stuchl4n3k
    • f3l1x