Open-source GeoIP API for Chitanda IP Site.
This repository provides the GeoIP backend used by the front-end project. It can run as a normal Node.js service, as a daily GitHub Release package with public databases included, or as a two-node primary-download / secondary-sync setup.
- Node.js
- systemd
- Nginx reverse proxy
- GitHub Actions
- GitHub Releases
/health,/myip,/geoip/{ip}, and/cdn-node/{provider}- plain-text client IP output for CLI probes
/api/*aliases for reverse-proxy deployments- public GeoIP database downloads
- release packaging with service scripts and examples
- automatic cleanup of older release directories
- Health check:
GET /healthandGET /api/healthreturn service readiness and the database open time. - Client IP endpoint:
GET /myipandGET /api/myipreturn the caller IP. WhenTRUST_PROXYis not0, proxy headers are honored before the socket address. - Plain client IP endpoint:
GET /myip?format=text,GET /api/myip?format=text, orAccept: text/plainon/myipreturn only the caller IP astext/plain. - GeoIP lookup:
GET /geoip/{ip},GET /geoip?ip=...,GET /api/geoip/{ip}, andGET /api/geoip?ip=...return a normalized IP profile. - Current visitor lookup:
GET /geoipandGET /api/geoipresolve the caller IP with the same GeoIP response fields. - CDN node probe:
GET /cdn-node/{provider}andGET /api/cdn-node/{provider}probefastly,akamai,virtuozzo, orovhand return the detected edge node. - Response fields: lookup responses may include
ip,country,country_code,region,region_code,city,postal_code,asn,asn_organization,organization,isp,timezone,offset,latitude,longitude, andcontinent_code. - Database readers: IPv4/IPv6 GeoLite2 City MMDB, ASN MMDB, Geo-Whois ASN Country MMDB, and ip2region IPv4/IPv6 XDB are opened on startup and shared by requests.
- Fallback logic: Mainland China records can use ip2region for Chinese region/city/ISP text; city-center tables fill missing coordinates for China and global locations.
- Localization and HTTP behavior:
Accept-LanguageandGEOIP_LANGcontrol localized names where available; JSON responses are CORS-enabled and usecache-control: no-store.
npm ci
npm run download-db
npm run smoke
HOST=127.0.0.1 PORT=3022 npm startDaily GitHub Release install:
curl -fsSL https://github.com/violetaini/chitanda-geoip-api/releases/latest/download/bootstrap-linux.sh | sudo bashchitanda-geoip-api-with-data.tar.gz includes:
- API source code
package.jsonandpackage-lock.json- public database files in
data/ - install and update scripts needed for deployment
- two-node sync scripts for the primary/secondary setup
- the minimum files required to install or update the service
GitHub Actions builds the package once per day and publishes a new data-YYYYMMDD GitHub Release.
After the Release is created, the workflow updates .github/badges/release.json and the README badge cache key so the badge shows the published tag without using Shields' GitHub API route.
Server updates are separate:
- The primary node checks the latest release.
- If a newer tag exists, it downloads the package and checksum.
- It verifies, installs, restarts, and health-checks the service.
- After success, it keeps only the newest 3 release directories.
- In the two-node setup, the primary node syncs the verified package to the secondary node.
- The secondary node applies the package locally and also keeps only the newest 3 release directories.
See Two-Node GeoIP Release Sync.
This API is meant for chitanda-ip-site. Point that project’s VITE_GEOIP_BASE at your API before building the front end.
MIT