Skip to content

GeoLite2 API

HTTPS API for IPv4 city, country, and ASN lookups.
When ip is omitted, the service uses the caller's observed public IPv4.

This service supports IPv4 only.

Base URLs

Use any of the following base URLs:

  • https://geolite2.ipcrystal.com
  • https://geolite2.kubectl.net
  • https://geolite2.websocket.cn

Common endpoint prefix:

1
/api/geolite2/lookup

Request conventions

Item Value
Method GET
Authentication None (public API)
Transport HTTPS
IP family IPv4 only
Automatic detection If ip is omitted, the caller's observed public IPv4 is used

Query parameters

ip (optional)

IPv4 address in dotted-decimal format.

Example:

1
8.8.8.8

Example validation regex:

1
^(25[0-5]|2[0-4]\d|1?\d{1,2})(\.(25[0-5]|2[0-4]\d|1?\d{1,2})){3}$

Lookup behavior:

  • ?ip=<IPv4>: Lookup for the specified address.
  • Omit ip: Lookup for the caller's observed public IPv4.

Endpoints

Endpoint Description Optional query parameter
/api/geolite2/lookup/city City-level geolocation ip
/api/geolite2/lookup/country Country-level geolocation ip
/api/geolite2/lookup/asn Autonomous System (ASN) data ip

All endpoints return lookup data for either the provided IPv4 address or the caller's observed public IPv4.

Examples

Set base URL

1
export GEOLITE2_BASE_URL="https://geolite2.ipcrystal.com"

Lookup caller IPv4

1
curl -sSL "${GEOLITE2_BASE_URL}/api/geolite2/lookup/city"

Lookup a specific IPv4

1
curl -sSL "${GEOLITE2_BASE_URL}/api/geolite2/lookup/city?ip=8.8.8.8"

Country lookup

1
curl -sSL "${GEOLITE2_BASE_URL}/api/geolite2/lookup/country?ip=8.8.8.8"

ASN lookup

1
curl -sSL "${GEOLITE2_BASE_URL}/api/geolite2/lookup/asn?ip=8.8.8.8"

Quick test via alternate domain

1
curl -sSL "https://geolite2.websocket.cn/api/geolite2/lookup/city"

Notes

  • IPv6 addresses are not supported.
  • Private, loopback, link-local, multicast, and invalid IPv4 addresses should not be used for public geolocation lookups.
  • Always use HTTPS to avoid exposing request metadata.
  • For reproducible results, explicitly provide the ip parameter.
  • For application integrations, validate input before sending requests and add retries with backoff.