Skip to main content
GET
Получить геолокацию по IP
The API operates with remarkable simplicity: just provide your API key along with an IP address, and you’ll receive comprehensive location data including postal codes, city names, regional information, country details, and precise latitude/longitude coordinates.

Getting started

REST Architecture

Similar to all Cleariflow APIs, the IP Geolocation API follows REST principles. It employs predictable, resource-oriented URLs and utilizes HTTP status codes for error indication.

HTTPS Security

All communications with the IP Geolocation API must be secured using TLS 1.2 or higher protocols.

API Versioning

All Cleariflow APIs incorporate versioning. The IP Geolocation API currently operates on Version 1.

Authentication with API Key

Your API key serves as the unique authentication credential for accessing the Cleariflow IP Geolocation API. It’s important to note that each Cleariflow API requires a distinct API key, meaning you’ll need separate keys for different services like IP Geolocation and Email Validation APIs. To authenticate your requests, append your API key to the base URL.

Base URL

Geolocation endpoint

The Cleariflow IP Geolocation API requires only your unique API key and automatically detects the IP address from the requesting client. Alternatively, you can include the “ip_address” parameter to specify a particular IP for analysis:
This represents a successful request, returning the IP address and associated details below:

Request parameters

String
required
Your unique API key. Note that each user has unique API keys for each of Cleariflow APIs, so your IP Geolocation API key will not work for your Email Validation API, for example.
String
The IP address to geolocate. Both IPv4 and IPv6 addresses are supported. Note that if you leave this parameter blank, the service will geolocate the IP address from which the request was made.
String
Comma-separated list of top-level response keys. Use ?fields=country,security to return the country and the complete security object. Nested keys such as is_tor_relay cannot be selected on their own.

Response parameters

The API response is returned in a universal and lightweight JSON format.
String
The IP address submitted for geolocation.
String
City’s name.
Integer
City’s geoname ID.
String
State or province in which the city is located.
Char[2]
State or province’s ISO 3166-2 code.
Integer
State or province’s geoname ID.
String
ZIP or postal code.
String
Country’s name.
Char[2]
Country’s ISO 3166-1 alpha-2 code.
Integer
Country’s geoname ID.
Boolean
True if the country is in the EU, false if it is not.
String
Continent’s name.
Char[2]
2 letter continent code: AF, AS, EU, NA, OC, SA, AN.
Integer
Continent’s geoname ID.
Float
Decimal of the longitude.
Float
Decimal of the latitude.
MaxMind supplies geolocation and ASN data. The supplemental Merged-IP database supplies network security signals.
Boolean
True when the IP is flagged as a VPN.
Boolean
True when a proxy is detected. Merged-IP proxy flags that overlap with hosting, CDN or anycast are treated as ambiguous.
String
VPN provider name, when available from the fallback VPN database.
Boolean
Tor relay detected, including relays that do not act as exit nodes. Present only when detected.
Boolean
Hosting network detected. Present only when detected.
Boolean
CDN or anycast infrastructure detected. Present only when detected.
String
Timezone’s name from the IANA Time Zone Database.
String
Timezone’s abbreviation, also from the IANA Time Zone Database.
Integer
Timezone’s offset from Greenwich Mean Time (GMT).
String
Current time in the local time zone.
Boolean
True if the location is currently in Daylight Savings Time (DST).
String
Link to a hosted version of the country’s flag in SVG format.
String
Link to a hosted version of the country’s flag in PNG format.
String
Country’s flag as an emoji.
String
Country’s flag in unicode.
String
The currency’s name.
String
The currency’s code in ISO 4217 format.
String
Inferred from the ASN organization name (for example, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN and proxy are reported in security, not here.
Uint32
Autonomous System number.
String
Autonomous System Organization name.
String
Internet Service Provider (ISP) name.
String
Organization name.

Limiting response fields

You can choose to only receive a few fields from the JSON response. To do so, you can include a fields value in the query parameters with a comma-separated list of the top-level keys you want to be returned. For example, a request to only get the country and city of an IP will look like this:
The response would look like this:

Use cases

Geolocating a website visitor

To request the geolocation from an IP address, simply include your unique API key in the template below. Note that you don’t need to know the IP of the visitor to make the request.
That’s all you need to get the geolocation and other data from a visitor! There is only one required parameter: your unique API key.

Response and error codes

Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below.

Country Codes

Below is a list of two-letter ISO 3166 Alpha 2 country codes that are used in the response. View this list in a CSV.

Other notes

Important billing information: Every IP address you process consumes one credit. Billing occurs per request submission, regardless of whether the response is successful. Therefore, even submitting an invalid IP address like “fda3346ds” will still deduct one credit from your account.

Query Parameters

api_key
string
required

API-ключ

ip_address
string

IP-адрес. Если не указан — используется IP клиента

fields
string

Список полей через запятую

Response

OK

ip_address
string | null
city
string | null
city_geoname_id
integer<int64> | null
region
string | null
region_iso_code
string | null
region_geoname_id
integer<int64> | null
postal_code
string | null
country
string | null
country_code
string | null
country_geoname_id
integer<int64> | null
country_is_eu
boolean
continent
string | null
continent_code
string | null
continent_geoname_id
integer<int64> | null
longitude
number<double> | null
latitude
number<double> | null
security
object

Security signals from a supplemental IP database. MaxMind supplies city and ASN. Use fields=security to include this block in filtered responses.

timezone
object
flag
object

png/svg only when asset exists on static.cleariflow.com (see country-flags)

currency
object

Static map for 197 country codes (CDN flag set); null if country_code not listed

connection
object