Lookup
IP Geolocation API
Cleariflow IP Geolocation API is a swift, efficient, contemporary, and RESTful JSON API that identifies the location and additional details of IP addresses across more than 190 countries.
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.
This represents a successful request, returning the IP address and associated details below:
The response would look like this:
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.
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:Request parameters
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.
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.
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. MaxMind supplies geolocation and ASN data. The supplemental Merged-IP database supplies network security signals.True when a proxy is detected. Merged-IP proxy flags that overlap with hosting, CDN or anycast are treated as ambiguous.
Tor relay detected, including relays that do not act as exit nodes. Present only when detected.
Inferred from the ASN organization name (for example, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN and proxy are reported in
security, not here.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: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.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
Response
OK