{"id":16843818,"url":"https://github.com/sapics/ip-location-api","last_synced_at":"2025-04-07T10:21:48.695Z","repository":{"id":255441986,"uuid":"851672692","full_name":"sapics/ip-location-api","owner":"sapics","description":"Fast and customizable nodejs api to get geolocation information from ip address","archived":false,"fork":false,"pushed_at":"2025-02-18T19:44:22.000Z","size":2684,"stargazers_count":30,"open_issues_count":2,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-19T12:53:28.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sapics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-03T14:15:39.000Z","updated_at":"2025-02-18T19:44:25.000Z","dependencies_parsed_at":"2024-09-10T14:41:53.592Z","dependency_job_id":"093791da-1a41-402c-b4dc-10bfcbfaa629","html_url":"https://github.com/sapics/ip-location-api","commit_stats":null,"previous_names":["sapics/ip-location-api"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapics%2Fip-location-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapics%2Fip-location-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapics%2Fip-location-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapics%2Fip-location-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sapics","download_url":"https://codeload.github.com/sapics/ip-location-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247631833,"owners_count":20970069,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T12:53:44.859Z","updated_at":"2025-04-07T10:21:48.661Z","avatar_url":"https://github.com/sapics.png","language":"JavaScript","readme":"# ip-location-api [![npm version](https://img.shields.io/npm/v/ip-location-api?color=success\u0026style=flat-square\u0026label=npm)](https://www.npmjs.com/package/ip-location-api)\n\nFast and customizable nodejs api to get geolocation information from ip address.\n`ip-location-api` make a fast lookup by using in-memory database.\n\nThis api is created for server-side javascript like Node.js.\nIf you need client-side javascript which works in **BROWSER**, please try to use [@iplookup/country](https://github.com/sapics/ip-location-api/tree/main/browser/country) or [@iplookup/geocode](https://github.com/sapics/ip-location-api/tree/main/browser/geocode).\n\n\n## Synopsis\n\n```javascript\nimport { lookup } from 'ip-location-api'\n// or CJS format\n// const { lookup } = require('ip-location-api')\n\nvar ip = \"207.97.227.239\"\nvar location = lookup(ip)\n// If you use Asynchronouns version which is configured with smallMemory=true,\n// var location = await lookup(ip)\n\nconsole.log(location)\n{\n  country: 'FR',\n  region1: 'NOR',\n  region1_name: 'Normandy',\n  region2: '27', \n  region2_name: 'Eure',\n  city: 'Heudicourt',\n  // metro: Defined only in US (Aug.2024)\n  timezone: 'Europe/Paris',\n  eu: 1,\n  latitude: 49.3335,\n  longitude: 1.6566,\n  area: 5,\n  postcode: 27860,\n  country_name: 'France',\n  country_native: 'France',\n  phone: [ 33 ],\n  continent: 'EU',\n  capital: 'Paris',\n  currency: [ 'EUR' ],\n  languages: [ 'fr' ],\n  continent_name: 'Europe'\n}\n```\n\n## Benchmark\n\nI make a benchmark for making comparison with intel 12700 (2.1GHz), SSD, nodejs v20.\nYou can change the memory usage or lookup time, by customizing location information.\n\n| benchmark | type | in-memory db | startup | lookup ipv4 | lookup ipv6 |\n| ---- | ---- | ---- |  ---- | ---- | ---- |\n| ip-location-api\u003cbr\u003e(default) | country | 6.9 MB  | 3 ms  | 0.362 μs/ip | 0.708 μs/ip |\n| ip-location-api\u003cbr\u003e(async)   | country | 2.9 MB  | 2 ms  | 243 μs/ip   | 255 μs/ip   |\n| ip-location-api              | city    | 62.9 MB | 14 ms | 0.751 μs/ip | 1.064 μs/ip |\n| ip-location-api\u003cbr\u003e(async)   | city    | 15.6 MB | 5 ms  | 267 μs/ip   | 271 μs/ip   |\n| [geoip-lite](https://github.com/geoip-lite/node-geoip)                  | city    | 136 MB  | 54 ms | 1.616 μs/ip | 3.890 μs/ip |\n| [fast-geoip](https://github.com/Doc999tor/fast-geoip)\u003cbr\u003e(async)        | city    | 0MB     | 4 ms  | 1714 μs/ip  | cannot lookup |\n\n\n## Installation\n\n```bash\n$ npm i ip-location-api\n```\n\n\n## API\n\nip-location-api has two modes which are synchronous and asynchronous.\nSynchronouns one load all data in-memory at startup time, thus it makes fast lookup.\nAsynchronouns one load smaller data in-memory at startup time, and the other data is loaded from the hard drive for each lookup.\n\n| type | memory usage | startup | lookup |\n| ---- | ---- | ---- |  ---- |\n| Synchronouns  | Large | Slow | Fast |\n| Asynchronouns | Small | Fast | Slow |\n\nIf you have a enough memory, I recommend to use synchronouns one because lookup is over 300 times faster than asynchronouns one.\n\n\n## Field description\n\nNote that as far as possible, the same field names as in `geoip-lite` are used, but some different field names are used.\n\n| `ip-location-api` | `geoip-lite` |  database |description |\n| ---- | ---- | ---- | ---- |\n| country | country | MaxMind | \"2 letter\" country code defined at [ISO-3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) |\n| region1 | region | MaxMind | region code which is short code for region1_name [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) |\n| region1_name  | ❌️ | MaxMind | first sub division name (multi language) |\n| region2 | ❌️ | MaxMind | region code which is short code for region2_name [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) |\n| region2_name  | ❌️ | MaxMind | second sub division name (multi language) |\n| city    | city |MaxMind |  city name (multi language) |\n| metro   | metro |MaxMind |  Geolocation target code from Google |\n| eu      | eu | MaxMind | true: the member state of the European Union, undefined: for the other countries. This needs \"country\" field. |\n| timezone  | timezone | MaxMind | time zone associated with location |\n| latitude  | ll[0] | MaxMind |  approximate [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) latitude |\n| longitude | ll[1] | MaxMind |  approximate [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) longitude |\n| area      | area | MaxMind | The radius in kilometers around the specified location where the IP address is likely to be. [maxmind blog](https://blog.maxmind.com/2022/06/using-maxminds-accuracy-radius/) |\n| postcode  | ❌️ | MaxMind | region-specific postal code near the IP address |\n| ❌️       | range | MaxMind | We removes range information for optimization |\n| country_name      | ❌️ | Countries| country name|\n| country_native    | ❌️ | Countries| country name in native language|\n| continent | ❌️ | Countries| continent short code|\n| continent_name | ❌️ | Countries| continent name|\n| capital   | ❌️ | Countries | capital name |\n| phone     | ❌️ | Countries| international country calling codes |\n| currency  | ❌️ | Countries | list of commonly used currencies |\n| languages | ❌️ | Countries | list of commonly used languages |\n\n\n## Setup the configuration\n\nYou can configure the api by 3 way.\n- CLI parameters: `ILA_FIELDS=latitude,longitude`\n- Environment variables: `ILA_FIELDS=latitude,longitude`\n- Javascript: `await reload({fields: 'latitude,longitude'})` .\n\nThe name of CLI prameter and environment variables are same.\n\n\nConf key in `reload(conf)` is named with \"LOWER CAMEL\", CLI or ENV parameter is named with \"SNAKE\" with adding \"ILA_\" (come from Ip-Location-Api).\n\n| `reload(conf)` | CLI or ENV | default | description |\n| ---- | ---- | ---- | ---- |\n| fields | ILA_FIELDS | country | You can change the fields to be retrived from [MaxMind](https://www.maxmind.com/). When you set \"all\", all fields are displayed. |\n| addCountryInfo | ILA_ADD_COUNTRY_INFO | false | \"true\" make to add the country information from [Countries](https://github.com/annexare/Countries). This needs \"country\" field. |\n| dataDir | ILA_DATA_DIR | ../data | Directory for database file |\n| tmpDataDir | ILA_TMP_DATA_DIR | ../tmp | Directory for temporary file |\n| apiDir | ILA_API_DIR | .. | Directory for ip-location-api |\n| smallMemory | ILA_SMALL_MEMORY | false | false: synchronouns, ture: asynchronouns |\n| smallMemoryFileSize | ILA_SMALL_MEMORY_FILE_SIZE | 4096 | Max file size for asynchronouns data (no change is recommended) |\n| licenseKey | ILA_LICENSE_KEY | redist | By setting [MaxMind](https://www.maxmind.com/) License key, you can download latest version of database from [MaxMind](https://www.maxmind.com/) server. By setting to \"redist\", you can download the database from [node-geolite2-redist](https://github.com/sapics/node-geolite2-redist) repository which re-distribute the GeoLite2 database. |\n| ipLocationDb | ILA_IP_LOCATION_DB | | When you need only \"country\" field, you can use [ip-location-db](https://github.com/sapics/ip-location-db) data |\n| downloadType | ILA_DOWNLOAD_TYPE | reuse | By setting to \"false\", \"tmpDataDir\" directory is deleted every update. \"reuse\" dose not delete \"tmpDataDir\" and re-use \"tmpDataDir\"'s database if the database file dose not update. |\n| autoUpdate | ILA_AUTO_UPDATE | default | By setting to \"false\", it dose not update automatically. \"default\" updates twice weekly. You can set CRON PATTERN FORMAT which is provided by [cron](https://github.com/kelektiv/node-cron) with UTC timezone (For example, ILA_AUTO_UPDATE=\"0 1 * * *\" for daily update). |\n| multiDbDir | ILA_MULTI_DB_DIR | false | If you use multiple \"dataDir\", please make this value to \"true\" |\n| series | ILA_SERIES | GeoLite2 | By setting to \"GeoIP2\", you can use premium database \"GeoIP2\" |\n| language | ILA_LANGUAGE | en | You can choose \"de\", \"en\", \"es\", \"fr\", \"ja\", \"pt-BR\", \"ru\", \"zh-CN\". By changing, the language of \"region1_name\", \"region2_name\", \"city\" fields are changed |\n| silent | ILA_SILENT | false | true: deactivate unnecessary console.log |\n\n\n## Update database\n\n```bash\nnpm run updatedb\n```\n\nor\n\n```javascript\nimport { updateDb } from 'ip-location-api'\nawait updateDb(setting)\n```\n\n\nThere are three database update way.\n- ILA_LICENSE_KEY=redist\n- ILA_LICENSE_KEY=YOUR_GEOLITE2_LICENSE_KEY\n- ILA_IP_LOCATION_DB=YOUR_CHOOSEN_DATABSE\n\nWhen you set \"ILA_LICENSE_KEY=redist\" which is the dafault setting, it downloads GeoLite2 database from the redistribution repository [node-geolite2-redist](https://github.com/sapics/node-geolite2-redist).\n\nWhen you set \"ILA_LICENSE_KEY=YOUR_GEOLITE2_LICENSE_KEY\", it downloads GeoLite2 dastabase from the MaxMind provided server.\n`YOUR_GEOLITE2_LICENSE_KEY` should be replaced by a valid GeoLite2 license key. Please [follow instructions](https://dev.maxmind.com/geoip/geoip2/geolite2/) provided by MaxMind to obtain a license key.\n\nWhen you set \"ILA_IP_LOCATION_DB=YOUR_CHOOSEN_DATABSE\", it downloads from the [ip-location-db](https://github.com/sapics/ip-location-db) (country type only).\nYou can \"YOUR_CHOOSEN_DATABSE\" from [ip-location-db](https://github.com/sapics/ip-location-db) with country type. For example, \"geolite2-geo-whois-asn\" is wider IP range country database which is equivalent to GeoLite2 database result for GeoLite2 country covered IP range and geo-whois-asn-country for the other IP range. \nThe other example, \"geo-whois-asn\" is [CC0 licensed database](https://github.com/sapics/ip-location-db/tree/main/geo-asn-country), if you are unable to apply the GeoLite2 License.\n\n\nAfter v2.0, the database is created automatically at initial startup, and updated automatically by setting `ILA_AUTO_UPDATE` which updates twice weekly with default setting.\n\n\n## How to use with an example\n\nWhen you need only geographic coordinates, please set \"ILA_FIELDS=latitude,longitude\".\nYou need to create a database for each configuration.\nAfter v2.0.0, the database is created at initial running (which takes some seconds), and auto update with `ILA_AUTO_UPDATE` which update twice weekly with default setting.\n\nThe database is created by following CLI\n\n```bash\n$ npm run updatedb ILA_FIELDS=latitude,longitude\n```\n\nor\n\n```bash\n$ ILA_FIELDS=latitude,longitude # set environment variable\n$ npm run updatedb\n```\n\nor you can create database with 'create.js' which includes the following.\n\n```javascript\nawait updateDb({fields:['latitude', 'longitude']})\n```\n\n\nThe CLI command for using `app.js` which uses `ip-location-api` is necessary to start with following CLI parameter\n\n```bash\n$ node app.js ILA_FIELDS=latitude,longitude\n```\n\nor environment variable\n\n```bash\n$ ILA_FIELDS=latitude,longitude # set environment variable\n$ node app.js\n```\n\nor you can write down configuration in `reload` function of app.js as\n\n```javascript\nawait reload({fields:['latitude', 'longitude']})\n// or await reload({fields:'latitude,longitude'})\n```\n\n\nIf you need all the data in above field table, setting \"ILA_FIELDS=all\" and \"ILA_ADD_COUNTRY_INFO=true\" is the one.\n\n\n| benchmark | in-memory db | startup | lookup ipv4 | lookup ipv6 |\n| ---- | ---- | ---- |  ---- | ---- |\n| longitude,latitude | 46.5 MB  | 10 ms  | 0.428 μs/ip | 0.776 μs/ip |\n| all                | 76.4 MB  | 18 ms  | 1.054 μs/ip | 1.348 μs/ip |\n\n\n## For module bundler (webpack, vite, next.js, etc)\n\nSome module bundlers cannot work with original database system.\nIf module bundlers could not work with `ip-location-api`, please try to import module as following.\nIt works almost same as original module.\n\n```js\nimport { lookup } from 'ip-location-api/pack'\n```\n\n\nIt would be better to set directories for database files which have write permission.\nWithout write permission directories, you cannot use this module.\n\n```bash\nILA_DATA_DIR=/your_database_directory\nILA_TMP_DATA_DIR=/your_tmporary_directory_for_database\n```\n\n\n## Node.js version\n\nThis library supports Node.js \u003e= 14 for ESM and CJS.\n\n\n## License and EULA\n\nThere are multiple licenses in this library, one for the software library, and the others for the datadata.\nPlease read the LICENSE and EULA files for details.\n\n\nThe license for the software itself is published under MIT License by [sapics](https://github.com/sapics).\n\n\nThe GeoLite2 database comes with certain restrictions and obligations, most notably:\n - You cannot prevent the library from updating the databases.\n - You cannot use the GeoLite2 data:\n   - for FCRA purposes,\n   - to identify specific households or individuals.\n\nYou can read [the latest version of GeoLite2 EULA](https://www.maxmind.com/en/geolite2/eula).\nGeoLite2 database is provided under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) by [MaxMind](https://www.maxmind.com/), so, you need to create attribusion to [MaxMind](https://www.maxmind.com/) for using GeoLite2 database.\n\n\nThe database of [Countries](https://github.com/annexare/Countries) is published under MIT license by [Annexare Studio](https://annexare.com/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapics%2Fip-location-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsapics%2Fip-location-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapics%2Fip-location-api/lists"}