Skip to main content

Lookup IP Address

Ⓔ Enterprise Only
This API is available exclusively in Countly Enterprise.

Endpoint​

/o?method=lookup

Overview​

Looks up location data for an IP address using geoip-lite.

Authentication​

  • Authentication methods:
    • API Key (parameter): api_key=YOUR_API_KEY
    • Auth Token (parameter): auth_token=YOUR_AUTH_TOKEN
    • Auth Token (header): countly-token: YOUR_AUTH_TOKEN

Permissions​

  • Required permission: Read on the geo feature

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringYes (or auth_token)API key authentication
auth_tokenStringYes (or api_key)Auth token authentication
app_idStringYesApplication context for permission validation
ip_addressStringNoIP address to lookup; when omitted, request IP is used

Response​

Success Response​

{
  "location": {
    "country": "US",
    "region": "CA",
    "city": "San Francisco",
    "ll": [37.7749, -122.4194]
  }
}

Response Fields​

FieldTypeDescription
locationObject or nullGeoIP lookup result for the provided/request IP
location.countryStringCountry code (when available)
location.regionStringRegion code (when available)
location.cityStringCity name (when available)
location.llArray[latitude, longitude] coordinates

Error Responses​

HTTP StatusResponse
400Validation/auth error from (for example missing required params)

Behavior/Processing​

  1. Resolves IP from ip_address or falls back to request IP.
  2. Performs lookup with geoip-lite.
  3. Returns result as { "location": ... }.

Database Collections​

This endpoint does not read or write database collections.

Examples​

Example 1: Lookup a Specific IP​

https://your-server.com/o?method=lookup&api_key=YOUR_API_KEY&app_id=609bd78d90d7a416d4dfb984&ip_address=8.8.8.8

Example 2: Lookup Request IP​

https://your-server.com/o?method=lookup&api_key=YOUR_API_KEY&app_id=609bd78d90d7a416d4dfb984

Ⓔ Enterprise​

This feature is part of Countly Enterprise.

Get Access:

Already a Customer? Use support portal if you have any questions

Last Updated​

2026-02-16