ciao121 / geo2city

Basic offline reverse geocode

geo2city

A tiny, portable, offline search, ip, and reverse geocode, also used in Life Diary ❤️, based on simplemaps.com's World Cities Database basic data.

import {ip, search, reverse} from 'geo2city';

search('Berlin, Germany').then(console.log);
// result (undefined if not found)
[ 52.5167, 13.3833 ]

reverse([52.52437, 13.41053]).then(console.log);
// result (undefined if not found)
{
  latitude: 52.5167,
  longitude: 13.3833,
  iso2: 'DE',
  iso3: 'DEU',
  flag: '🇩🇪',
  country: 'Germany',
  city: 'Berlin'
}

// ⚠ requires geoiplookup (via geoip)
//   and geoip-database-extra
ip('216.58.197.78').then(console.log);
// result (undefined if not found)
{
  latitude: 37.4,
  longitude: -122.0796,
  iso2: 'US',
  iso3: 'USA',
  flag: '🇺🇸',
  country: 'United States',
  city: 'Mountain View'
}

Details

Geo search and reverse geocode is complicated and expensive, and it usually requires some API or network access to be performed, with all usual limitations.

This module takes a different approach, it ships a pre-optimized SQLite database which, once zipped, is no more than 700K (5MB once unzipped), and it can be used offline.

Features

• 26563 cities and related countries
• country name, iso2, iso3, and emoji flag, per each country
• reverse search via geo2city.reverse([latitude, longitude]) with nearest city approximation
• IPv4 reverse search via geo2city.ip('1.1.1.1') with nearest city approximation
• full text search via geo2city.search('City, Country Name or ISO') with highest ranked result

Attribution

The World Cities Database has a CC BY 4.0 license and requires a backlink to simplemaps.com, example:

Geo data by <a href="https://simplemaps.com/data/world-cities">simplemaps</a>

The social media image is also readapted from simplemaps.

About Pro / Comprehensive Database

Unfortunately, these versions of the database don't allow redistribution, but if you fork this project and run npm i after, then you change worldcities.csv with the Pro or Comprehensive database CSV version, and then you run npm run import before running npm run postinstall, you should have a working copy of geo2city pointing at a much more accurate dataset.

The country table would likely be the same, but the city one should contain all millions cities offered by simplemaps.

To succeed, you need any Linux or macOS with sqlite3 and zip installed, however, I am not planning to support these versions, or provide help with these, because these are out of scope for this project.

P.S. as I haven't tried myself, it is possible that the worldcities_csv table in sqlite/import.sql should be modified to contain all fields provided by the bigger .csv file, but as long as field names are the same for the interested data, everything should go rather smoothly.