IP Geolocation API

A free, open source REST API to geolocate IPv4 and IPv6 addresses. Returns country, city, timezone, and coordinates — powered by the MaxMind GeoLite2 database, self-hosted with no third-party calls.

✓ Free & Open Source ✓ No API Key Required Self-Hostable Offline Database MIT License

Overview

The API uses the MaxMind GeoLite2-City database, which is bundled with the server. No external call is made at request time — all lookups happen locally, making responses fast and privacy-preserving.

Field	Description	Example
`country_code`	ISO 3166-1 alpha-2 country code	`FR`
`country_name`	Full country name	`France`
`continent`	Continent name	`Europe`
`city`	City name (may be null)	`Paris`
`postal_code`	Postal / ZIP code (may be null)	`75001`
`latitude`	Approximate latitude	`48.8534`
`longitude`	Approximate longitude	`2.3488`
`timezone`	IANA timezone identifier	`Europe/Paris`
`accuracy_radius_km`	Estimated accuracy in km	`50`

⚠️ Geolocation is approximate. City-level accuracy is typical but not guaranteed. Do not use for legal enforcement, precise targeting, or security-critical decisions.

Base URL

https://ip-geolocation-api-31u6.onrender.com

All responses are application/json. Supports IPv4 and IPv6.

⚠️ The public instance runs on Render's free tier and may spin down after inactivity. The first request after a cold start can take up to 60 seconds (the database is also downloaded at startup) — subsequent requests are fast.

Authentication

🔓 No authentication required. All endpoints are publicly accessible. CORS is enabled for all origins.

Rate Limiting

Endpoint	Limit
`GET /geolocate/{ip}`	60 requests / minute per IP
`GET /geolocate/me`	60 requests / minute per IP
`POST /geolocate/batch`	10 requests / minute per IP
`GET /country/{ip}`	120 requests / minute per IP
`GET /timezone/{ip}`	120 requests / minute per IP

Exceeded limits return HTTP 429 with a Retry-After header.

GeoLite2 Database

This API uses the MaxMind GeoLite2-City database, available for free under the Creative Commons Attribution-ShareAlike 4.0 license.

The database is updated by MaxMind every Tuesday. For self-hosted instances, we recommend scheduling a weekly update.

📦 The .mmdb database file is not included in the repository (it's in .gitignore). Download it from dev.maxmind.com and place it in the project root before starting the server.

Endpoints

GET /geolocate/{ip} Full geolocation for an IP address

Path Parameters

Parameter	Type	Description
`ip`	string	IPv4 or IPv6 address to geolocate.

Example Request

curl https://ip-geolocation-api-31u6.onrender.com/geolocate/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States",
  "continent": "North America",
  "city": "Mountain View",
  "postal_code": "94043",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "accuracy_radius_km": 1000
}

GET /geolocate/me Geolocate the caller's IP address

Detects the IP from the X-Forwarded-For header (set by Render's proxy) or the direct connection IP. Returns the same schema as /geolocate/{ip}.

Example Request

curl https://ip-geolocation-api-31u6.onrender.com/geolocate/me

POST /geolocate/batch Geolocate up to 10 IPs at once

Request Body

Field	Type	Required	Description
`ips`	string[]	required	Array of IP addresses. Max 10.

Example Request

curl -X POST https://ip-geolocation-api-31u6.onrender.com/geolocate/batch \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'

Example Response

{
  "count": 2,
  "results": [
    { "ip": "8.8.8.8", "country_code": "US", "country_name": "United States", "city": "Mountain View", "timezone": "America/Los_Angeles", "..." : "..." },
    { "ip": "1.1.1.1", "country_code": "AU", "country_name": "Australia", "city": "Sydney", "timezone": "Australia/Sydney", "...": "..." }
  ]
}

GET /country/{ip} Lightweight country-only lookup

Faster and lighter than the full geolocation — returns only country and continent data.

Example Request

curl https://ip-geolocation-api-31u6.onrender.com/country/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States",
  "continent": "North America"
}

GET /timezone/{ip} Get timezone and coordinates for an IP

Example Request

curl https://ip-geolocation-api-31u6.onrender.com/timezone/8.8.8.8

Example Response

{
  "ip": "8.8.8.8",
  "timezone": "America/Los_Angeles",
  "latitude": 37.386,
  "longitude": -122.0838
}

GET /health Health check — also reports database status

{ "status": "ok", "database": "available" }

Returns "database": "missing" if the .mmdb file is not present.

Error Codes

Code	Meaning	Common Cause
400	Bad Request	Invalid IP address format, batch exceeds 10 items.
422	Unprocessable Entity	POST body is not valid JSON or missing `Content-Type: application/json` header (affects `POST /geolocate/batch`).
404	Not Found	IP address not found in the database (private ranges, unallocated blocks).
429	Too Many Requests	Rate limit exceeded.
503	Service Unavailable	GeoLite2 database file is missing from the server.

Error Response Format

{ "detail": "No data found for IP: 192.168.1.1" }

💡 Private IP ranges (10.x.x.x, 192.168.x.x, 127.x.x.x) will return a 404 — they are not in the geolocation database by design.

Legal & GDPR

Data Retention

No IP addresses are stored, logged, or shared. All lookups are performed in memory and discarded immediately after the response is sent.

GDPR Compliance

IP addresses are considered personal data under GDPR in the EU. This API does not persist IP data, functioning as a pure real-time processing tool. Integrators must ensure they have a lawful basis for processing IP addresses collected from their own users (e.g. legitimate interest, consent).

GeoLite2 Database License

The GeoLite2 data is provided by MaxMind under the Creative Commons Attribution-ShareAlike 4.0 license. When self-hosting, you must comply with MaxMind's End User License Agreement and provide attribution in your application.

Attribution example: "This product includes GeoLite2 data created by MaxMind, available from maxmind.com."

Accuracy Disclaimer

Geolocation data is approximate. Do not use this API for legal enforcement, fraud detection as a sole signal, or any context where precise location is required.

Acceptable Use

Must not be used to track, profile, or surveil individuals without their consent. Bulk scraping or building derivative geolocation databases from the API output is prohibited under MaxMind's terms.

License

API source code is released under the MIT License.

Self-Hosting

1. Get the GeoLite2 database

Create a free account at dev.maxmind.com, download GeoLite2-City.mmdb, and place it in the project root.

2. Run locally

git clone https://github.com/GregorySpro/ip-geolocation-api
cd ip-geolocation-api
pip install -r requirements.txt
# Place GeoLite2-City.mmdb in this directory
uvicorn main:app --reload

3. Keep the database up to date

MaxMind updates GeoLite2 every Tuesday. Use their GeoIP Update tool or a weekly cron job to refresh the file.

Deploy on Render

The repo includes a start.sh script that automatically downloads the GeoLite2-City database from MaxMind at startup using your license key. Set the MAXMIND_LICENSE_KEY environment variable in your Render service, then set the Start Command to bash start.sh. The render.yaml handles the rest.