> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

```
https://ipgeolocation.cleariflow.com/v1/
```

### 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:

```
https://ipgeolocation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& ip_address = 94.198.41.118 (optional)
```

This represents a successful request, returning the IP address and associated details below:

<ResponseExample>
  ```json theme={"system"}
  {
      "ip_address": "80.255.13.30",
      "city": null,
      "city_geoname_id": null,
      "region": null,
      "region_iso_code": null,
      "region_geoname_id": null,
      "postal_code": null,
      "country": "Germany",
      "country_code": "DE",
      "country_geoname_id": 2921044,
      "country_is_eu": true,
      "continent": "Europe",
      "continent_code": "EU",
      "continent_geoname_id": 6255148,
      "longitude": 9.491,
      "latitude": 51.2993,
      "security": {
          "is_vpn": true,
          "is_proxy": false,
          "vpn_provider": "NordVPN"
      },
      "timezone": {
          "name": "Europe/Berlin",
          "abbreviation": "CEST",
          "gmt_offset": 2,
          "current_time": "21:21:22",
          "is_dst": true
      },
      "flag": {
          "emoji": "🇩🇪",
          "unicode": "U+1F1E9 U+1F1EA",
          "png": "https://static.cleariflow.com/country-flags/DE_flag.png",
          "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg"
      },
      "currency": {
          "currency_name": "Euros",
          "currency_code": "EUR"
      },
      "connection": {
          "autonomous_system_number": 201011,
          "autonomous_system_organization": "Core-Backbone GmbH",
          "connection_type": null,
          "isp_name": null,
          "organization_name": null
      }
  }
  ```
</ResponseExample>

### Request parameters

<ParamField query="api_key" type="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.
</ParamField>

<ParamField query="ip_address" type="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.
</ParamField>

<ParamField query="fields" type="String">
  Comma-separated list of **top-level** keys to return (for example, `?fields=country,security`). To include VPN/proxy flags, use `security` — the whole object is returned (`is_vpn`, `is_proxy`, and `vpn_provider` when present). Nested keys such as `is_vpn` alone are not supported.
</ParamField>

### Response parameters

The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).

<ResponseField name="ip_address" type="String">
  The IP address submitted for geolocation.
</ResponseField>

<ResponseField name="city" type="String">
  City's name.
</ResponseField>

<ResponseField name="city_geoname_id" type="String">
  City's geoname ID.
</ResponseField>

<ResponseField name="region" type="String">
  State or province in which the city is located.
</ResponseField>

<ResponseField name="region_iso_code" type="Char[2]">
  State or province's ISO 3166-2 code.
</ResponseField>

<ResponseField name="region_geoname_id" type="String">
  State or province's geoname ID.
</ResponseField>

<ResponseField name="postal_code" type="String">
  ZIP or postal code.
</ResponseField>

<ResponseField name="country" type="String">
  Country's name.
</ResponseField>

<ResponseField name="country_code" type="Char[2]">
  Country's ISO 3166-1 alpha-2 code.
</ResponseField>

<ResponseField name="country_geoname_id" type="String">
  Country's geoname ID.
</ResponseField>

<ResponseField name="country_is_eu" type="Boolean">
  True if the country is in the EU, false if it is not.
</ResponseField>

<ResponseField name="continent" type="String">
  Continent's name.
</ResponseField>

<ResponseField name="continent_code" type="Char[2]">
  2 letter continent code: AF, AS, EU, NA, OC, SA, AN.
</ResponseField>

<ResponseField name="continent_geoname_id" type="String">
  Continent's geoname ID.
</ResponseField>

<ResponseField name="longitude" type="Float">
  Decimal of the longitude.
</ResponseField>

<ResponseField name="latitude" type="Float">
  Decimal of the latitude.
</ResponseField>

<ResponseField name="security.is_vpn" type="Boolean">
  `true` when the IP matches the enumerated VPN exit-node database (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.is_proxy" type="Boolean">
  `true` when the IP matches the proxy database (IP-to-VPN MMDB).
</ResponseField>

<ResponseField name="security.vpn_provider" type="String">
  VPN service name from the MMDB (for example, `NordVPN`). Omitted when `is_vpn` is `false`.
</ResponseField>

<ResponseField name="timezone.name" type="String">
  Timezone's name from the IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.abbreviation" type="String">
  Timezone's abbreviation, also from the IANA Time Zone Database.
</ResponseField>

<ResponseField name="timezone.gmt_offset" type="String">
  Timezone's offset from Greenwich Mean Time (GMT).
</ResponseField>

<ResponseField name="timezone.current_time" type="String">
  Current time in the local time zone.
</ResponseField>

<ResponseField name="timezone.is_dst" type="Boolean">
  True if the location is currently in Daylight Savings Time (DST).
</ResponseField>

<ResponseField name="flag.svg" type="String">
  Link to a hosted version of the country's flag in SVG format.
</ResponseField>

<ResponseField name="flag.png" type="String">
  Link to a hosted version of the country's flag in PNG format.
</ResponseField>

<ResponseField name="flag.emoji" type="String">
  Country's flag as an emoji.
</ResponseField>

<ResponseField name="flag.unicode" type="String">
  Country's flag in unicode.
</ResponseField>

<ResponseField name="currency.currency_name" type="String">
  The currency's name.
</ResponseField>

<ResponseField name="currency.currency_code" type="String">
  The currency's code in ISO 4217 format.
</ResponseField>

<ResponseField name="connection.connection_type" type="String">
  Inferred from the ASN organization name (for example, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN and proxy are reported in `security`, not here.
</ResponseField>

<ResponseField name="connection.autonomous_system_number" type="Uint32">
  Autonomous System number.
</ResponseField>

<ResponseField name="connection.autonomous_system_organization" type="String">
  Autonomous System Organization name.
</ResponseField>

<ResponseField name="connection.isp_name" type="String">
  Internet Service Provider (ISP) name.
</ResponseField>

<ResponseField name="connection.organization_name" type="String">
  Organization name.
</ResponseField>

### 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:

```
https://ipgeolocation.cleariflow.com/v1/
    ? api_key = YOUR_API_KEY
    & ip_address = 94.198.41.122
    & fields = country,city
```

The response would look like this:

```json theme={"system"}
{
    "city": "Vienna",
    "country": "Austria"
}
```

## 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.

```javascript theme={"system"}
$.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) {
   console.log(data.ip_address);
   console.log(data.country);
})
```

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.

| Code | Type                  | Details                                                                                                                                                     |
| ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Everything worked as expected.                                                                                                                              |
| 204  | OK                    | There is no location data for the submitted IP.                                                                                                             |
| 400  | Bad request           | Bad request.                                                                                                                                                |
| 401  | Unauthorized          | The request was unacceptable. Typically due to the API key missing or incorrect.                                                                            |
| 422  | Quota reached         | The request was aborted due to insufficient API credits. (Free plans)                                                                                       |
| 429  | Too many requests     | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. |
| 500  | Internal server error | The request could not be completed due to an error on the server side.                                                                                      |
| 503  | Service unavailable   | The server was unavailable.                                                                                                                                 |

## 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](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing).

| Country name                     | Country code |
| -------------------------------- | ------------ |
| Afghanistan                      | AF           |
| Albania                          | AL           |
| Algeria                          | DZ           |
| American Samoa                   | AS           |
| Andorra                          | AD           |
| Angola                           | AO           |
| Anguilla                         | AI           |
| Antigua and Barbuda              | AG           |
| Argentina                        | AR           |
| Armenia                          | AM           |
| Aruba                            | AW           |
| Australia                        | AU           |
| Austria                          | AT           |
| Azerbaijan                       | AZ           |
| Bahrain                          | BH           |
| Bangladesh                       | BD           |
| Barbados                         | BB           |
| Belarus                          | BY           |
| Belgium                          | BE           |
| Belize                           | BZ           |
| Benin                            | BJ           |
| Bermuda                          | BM           |
| Bhutan                           | BT           |
| Bolivia                          | BO           |
| Bosnia and Herzegovina           | BA           |
| Botswana                         | BW           |
| Brazil                           | BR           |
| British Virgin Islands           | VG           |
| Brunei                           | BN           |
| Bulgaria                         | BG           |
| Burkina Faso                     | BF           |
| Burundi                          | BI           |
| Cabo Verde                       | CV           |
| Cambodia                         | KH           |
| Cameroon                         | CM           |
| Canada                           | CA           |
| Cayman Islands                   | KY           |
| Central African Republic         | CF           |
| Chad                             | TD           |
| Chile                            | CL           |
| China                            | CN           |
| Colombia                         | CO           |
| Comoros                          | KM           |
| Congo                            | CG           |
| Congo Democratic Republic        | CD           |
| Cook Islands                     | CK           |
| Costa Rica                       | CR           |
| Cote d'Ivoire                    | CI           |
| Croatia                          | HR           |
| Cuba                             | CU           |
| Curaçao                          | CW           |
| Cyprus                           | CY           |
| Czechia                          | CZ           |
| Denmark                          | DK           |
| Djibouti                         | DJ           |
| Dominica                         | DM           |
| Dominican Republic               | DO           |
| East Timor                       | TL           |
| Ecuador                          | EC           |
| Egypt                            | EG           |
| El Salvador                      | SV           |
| Equatorial Guinea                | GQ           |
| Eritrea                          | ER           |
| Estonia                          | EE           |
| eSwatini                         | SZ           |
| Ethiopia                         | ET           |
| Falkland Islands                 | FK           |
| Faroe Islands                    | FO           |
| Fiji                             | FJ           |
| Finland                          | FI           |
| France                           | FR           |
| French Guiana                    | GF           |
| French Polynesia                 | PF           |
| Gabon                            | GA           |
| Gambia                           | GM           |
| Georgia                          | GE           |
| Germany                          | DE           |
| Ghana                            | GH           |
| Gibraltar                        | GI           |
| Greece                           | GR           |
| Greenland                        | GL           |
| Grenada                          | GD           |
| Guadeloupe                       | GP           |
| Guam                             | GU           |
| Guatemala                        | GT           |
| Guernsey                         | GG           |
| Guinea                           | GN           |
| Guinea-Bissau                    | GW           |
| Guyana                           | GY           |
| Haiti                            | HT           |
| Honduras                         | HN           |
| Hong Kong                        | HK           |
| Hungary                          | HU           |
| Iceland                          | IS           |
| India                            | IN           |
| Indonesia                        | ID           |
| Iran                             | IR           |
| Iraq                             | IQ           |
| Ireland                          | IE           |
| Isle of Man                      | IM           |
| Israel                           | IL           |
| Italy                            | IT           |
| Jamaica                          | JM           |
| Japan                            | JP           |
| Jersey                           | JE           |
| Jordan                           | JO           |
| Kazakhstan                       | KZ           |
| Kenya                            | KE           |
| Kiribati                         | KI           |
| Kosovo                           | XK           |
| Kuwait                           | KW           |
| Kyrgyzstan                       | KG           |
| Laos                             | LA           |
| Latvia                           | LV           |
| Lebanon                          | LB           |
| Lesotho                          | LS           |
| Liberia                          | LR           |
| Libya                            | LY           |
| Liechtenstein                    | LI           |
| Lithuania                        | LT           |
| Luxembourg                       | LU           |
| Macau                            | MO           |
| Madagascar                       | MG           |
| Malawi                           | MW           |
| Malaysia                         | MY           |
| Maldives                         | MV           |
| Mali                             | ML           |
| Malta                            | MT           |
| Marshall Islands                 | MH           |
| Martinique                       | MQ           |
| Mauritania                       | MR           |
| Mauritius                        | MU           |
| Mayotte                          | YT           |
| Mexico                           | MX           |
| Micronesia                       | FM           |
| Moldova                          | MD           |
| Monaco                           | MC           |
| Mongolia                         | MN           |
| Montenegro                       | ME           |
| Montserrat                       | MS           |
| Morocco                          | MA           |
| Mozambique                       | MZ           |
| Myanmar                          | MM           |
| Namibia                          | NA           |
| Nauru                            | NR           |
| Nepal                            | NP           |
| Netherlands                      | NL           |
| New Caledonia                    | NC           |
| New Zealand                      | NZ           |
| Nicaragua                        | NI           |
| Niger                            | NE           |
| Nigeria                          | NG           |
| North Korea                      | KP           |
| North Macedonia                  | MK           |
| Northern Mariana Islands         | MP           |
| Norway                           | NO           |
| Oman                             | OM           |
| Pakistan                         | PK           |
| Palau                            | PW           |
| Panama                           | PA           |
| Papua New Guinea                 | PG           |
| Paraguay                         | PY           |
| Peru                             | PE           |
| Philippines                      | PH           |
| Poland                           | PL           |
| Portugal                         | PT           |
| Puerto Rico                      | PR           |
| Qatar                            | QA           |
| Reunion                          | RE           |
| Romania                          | RO           |
| Russia                           | RU           |
| Rwanda                           | RW           |
| Saint Helena                     | SH           |
| Saint Kitts and Nevis            | KN           |
| Saint Lucia                      | LC           |
| Saint Martin                     | MF           |
| Saint Pierre and Miquelon        | PM           |
| Saint Vincent and the Grenadines | VC           |
| Samoa                            | WS           |
| San Marino                       | SM           |
| Sao Tome and Principe            | ST           |
| Saudi Arabia                     | SA           |
| Senegal                          | SN           |
| Serbia                           | RS           |
| Seychelles                       | SC           |
| Sierra Leone                     | SL           |
| Singapore                        | SG           |
| Sint Maarten                     | SX           |
| Slovakia                         | SK           |
| Slovenia                         | SI           |
| Solomon Islands                  | SB           |
| Somalia                          | SO           |
| South Africa                     | ZA           |
| South Korea                      | KR           |
| South Sudan                      | SS           |
| Spain                            | ES           |
| Sri Lanka                        | LK           |
| St. Barts                        | BL           |
| Sudan                            | SD           |
| Suriname                         | SR           |
| Sweden                           | SE           |
| Switzerland                      | CH           |
| Syria                            | SY           |
| Taiwan                           | TW           |
| Tajikistan                       | TJ           |
| Tanzania                         | TZ           |
| Thailand                         | TH           |
| The Bahamas                      | BS           |
| Togo                             | TG           |
| Tonga                            | TO           |
| Trinidad and Tobago              | TT           |
| Tunisia                          | TN           |
| Turkey                           | TR           |
| Turkmenistan                     | TM           |
| Turks and Caicos Islands         | TC           |
| Tuvalu                           | TV           |
| Uganda                           | UG           |
| Ukraine                          | UA           |
| United Arab Emirates             | AE           |
| United Kingdom                   | GB           |
| United States                    | US           |
| Uruguay                          | UY           |
| US Virgin Islands                | VI           |
| Uzbekistan                       | UZ           |
| Vanuatu                          | VU           |
| Vatican City (Holy See)          | VA           |
| Venezuela                        | VE           |
| Vietnam                          | VN           |
| Wallis and Futuna                | WF           |
| Yemen                            | YE           |
| Zambia                           | ZM           |
| Zimbabwe                         | ZW           |

## 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.