@hebcal/geo-sqlite

Hebcal ES6 interface to GeoNames and USA ZIP code SQLite databases

This package is designed for the hebcal.com and may not be generally reusable. It requires two separate databases, one made from GeoNames.org data (available via a Creative Commons license) and a USA ZIP code database (commercial license).

Installation

$ npm install @hebcal/geo-sqlite
$ ./node_modules/.bin/download-and-make-dbs

Synopsis

import {Location} from '@hebcal/core';
import {GeoDb} from '@hebcal/geo-sqlite';
import pino from 'pino';
const logger = pino();

const db = new GeoDb(logger, 'zips.sqlite3', 'geonames.sqlite3');
const loc1 = db.lookupZip('90210'); // Beverly Hills, California
const loc2 = db.lookupGeoname(293397); // Tel Aviv
const loc3 = db.lookupLegacyCity('IL-Netanya');
db.close();

Data attribution

Some location data is incorporated directly into this package, including the bundled fixtures used by make-test-dbs to build test databases (the ~60 "classic" Hebcal cities, cities-patch.txt, and related country/admin1 data). This data is derived from GeoNames.org and is used under the Creative Commons Attribution 4.0 License.

Classes

Functions

GeoDb

Wrapper around sqlite databases

Kind: global class

• GeoDb
  • new GeoDb(logger, zipsFilename, geonamesFilename, options)
  • instance
    • .zipCache : Map.<string, Location>
    • .geonamesCache : Map.<number, Location>
    • .legacyCities : Map.<string, number>
    • .countryNames : Map.<string, string>
    • .close()
    • .lookupZip(zip) ⇒ Location
    • .lookupGeoname(geonameid) ⇒ Location
    • .lookupLegacyCity(cityName) ⇒ Location
    • .autoComplete(qraw, latlong) ⇒ Array.<Object>
    • .cacheZips()
    • .cacheGeonames()
  • static
    • .transliterate(source, [options]) ⇒ string
    • .geonameCityDescr(cityName, admin1, countryName) ⇒ string
    • .version()
    • .is5DigitZip(str) ⇒ boolean

new GeoDb(logger, zipsFilename, geonamesFilename, options)

| Param | Type | | --- | --- | | logger | any | | zipsFilename | string | | geonamesFilename | string | | options | any |

geoDb.zipCache : Map.<string, Location>

Kind: instance property of GeoDb

geoDb.geonamesCache : Map.<number, Location>

Kind: instance property of GeoDb

geoDb.legacyCities : Map.<string, number>

Kind: instance property of GeoDb

geoDb.countryNames : Map.<string, string>

Kind: instance property of GeoDb

geoDb.close()

Closes database handles

Kind: instance method of GeoDb

geoDb.lookupZip(zip) ⇒ Location

Kind: instance method of GeoDb

| Param | Type | | --- | --- | | zip | string |

geoDb.lookupGeoname(geonameid) ⇒ Location

Kind: instance method of GeoDb

| Param | Type | | --- | --- | | geonameid | number |

geoDb.lookupLegacyCity(cityName) ⇒ Location

Kind: instance method of GeoDb

| Param | Type | | --- | --- | | cityName | string |

geoDb.autoComplete(qraw, latlong) ⇒ Array.<Object>

Generates autocomplete results based on a query string

Kind: instance method of GeoDb

| Param | Type | Default | | --- | --- | --- | | qraw | string | | | latlong | boolean | false |

geoDb.cacheZips()

Reads entire ZIP database and caches in-memory

Kind: instance method of GeoDb

geoDb.cacheGeonames()

Reads entire geonames database and caches in-memory

Kind: instance method of GeoDb

GeoDb.transliterate(source, [options]) ⇒ string

Convenience wrapper of the transliterate function from transliteration npm package. Transliterate the string source and return the result.

Kind: static method of GeoDb

| Param | Type | | --- | --- | | source | string | | [options] | any |

GeoDb.geonameCityDescr(cityName, admin1, countryName) ⇒ string

Builds a city description from geonameid string components

Kind: static method of GeoDb

| Param | Type | Description | | --- | --- | --- | | cityName | string | e.g. 'Tel Aviv' or 'Chicago' | | admin1 | string | e.g. 'England' or 'Massachusetts' | | countryName | string | full country name, e.g. 'Israel' or 'United States' |

GeoDb.version()

Returns the version of the GeoDb package

Kind: static method of GeoDb

GeoDb.is5DigitZip(str) ⇒ boolean

Kind: static method of GeoDb

| Param | Type | | --- | --- | | str | string |

buildGeonamesSqlite(opts)

Builds geonames.sqlite3 from files downloaded from geonames.org

Kind: global function

| Param | Type | | --- | --- | | opts | any |

doSql(logger, db, ...sqls)

Kind: global function

| Param | Type | | --- | --- | | logger | pino.Logger | | db | Database | | ...sqls | string |

doFile(logger, db, infile, tableName, expectedFields, callback)

Kind: global function

| Param | Type | | --- | --- | | logger | pino.Logger | | db | Database | | infile | string | | tableName | string | | expectedFields | number | | callback | function |

makeZipsSqlite(dbFilename, sqlFile)

Builds zips.sqlite3 from the bundled zips-dummy.sql schema file

Kind: global function

| Param | Type | Description | | --- | --- | --- | | dbFilename | string | path to the output SQLite database file | | sqlFile | string | path to the SQL schema file |