IP-API Geolocation API

https://ip-api.com/docs
Admin
IP-API Geolocation API offers a simple URL-based HTTP interface for developers to query IP addresses...
Tokens:13,515
Snippets:48
Trust Score:9.9
Update:11 months ago
Show doc for...
Tokens:
Raw
### JSONP Callback Example

Source: https://ip-api.com/docs/dns

Demonstrates how to enable JSONP by appending the 'callback' GET parameter to the API request URL. This allows the response to be processed by a specified JavaScript function.

```http
http://edns.ip-api.com/json/?callback=_{callback}_
```

--------------------------------

### Localization Example

Source: https://ip-api.com/docs/api%3Ajson

Illustrates how to retrieve localized geolocation data using the `lang` query parameter.

```APIDOC
## GET /json/{query}?lang=...

### Description
Request localized names for city, region, and country by specifying the desired language using the `lang` query parameter.

### Method
GET

### Endpoint
`http://ip-api.com/json/{query}`

### Query Parameters
- **lang** (string) - Required - The ISO 639 language code (e.g., `de`, `es`, `fr`, `ja`, `zh-CN`, `ru`). `en` is the default.

### Request Example (German)
```
http://ip-api.com/json/?lang=de
```

### Response Example (with lang=de)
```json
{
  "query": "8.8.8.8",
  "status": "success",
  "country": "Vereinigte Staaten",
  "countryCode": "US",
  "region": "CA",
  "regionName": "Kalifornien",
  "city": "Mountain View",
  "zip": "94043",
  "lat": 37.4219,
  "lon": -122.084,
  "timezone": "America/Los_Angeles",
  "isp": "Google",
  "org": "Google",
  "as": "AS15169 Google LLC",
  "asname": "GOOGLE",
  "reverse": "dns.google",
  "mobile": false,
  "proxy": false,
  "hosting": true
}
```
```

--------------------------------

### JavaScript Example: Geo-based Redirection

Source: https://ip-api.com/docs/api%3Ajson

An example script demonstrating how to redirect users based on their country code.

```APIDOC
## JavaScript Example: Geo-based Redirection

### Description

This script redirects users to different URLs based on their detected country code. For example, users from the US are redirected to `https://google.com/`, and users from Canada are redirected to `https://google.ca/`.

### Endpoint

`http://ip-api.com/json/?fields=status,message,countryCode`

### Request Example

```javascript
// ip-api endpoint URL
// we need only the countryCode, but you can request more fields
// see http://ip-api.com/docs/api:json for documentation
var endpoint = 'http://ip-api.com/json/?fields=status,message,countryCode';

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Redirect
		if(response.countryCode == "US") {
			window.location.replace("https://google.com/");
		}
		if(response.countryCode == "CA") {
			window.location.replace("https://google.ca/");
		}
	}
};
xhr.open('GET', endpoint, true);
xhr.send();
```

### Response Example (Success)

```json
{
  "status": "success",
  "message": "private range",
  "countryCode": "US"
}
```

### Response Example (Error)

```json
{
  "status": "fail",
  "message": "invalid query string",
  "countryCode": null
}
```
```

--------------------------------

### JavaScript Example: Distance Calculation

Source: https://ip-api.com/docs/api%3Ajson

An example script for calculating the distance from the user's IP location to multiple specified points.

```APIDOC
## JavaScript Example: Distance Calculation

### Description

This script calculates and logs the distance in kilometers from the user's current location (determined by their IP address) to a predefined list of geographical points.

### Endpoint

`http://ip-api.com/json/?fields=status,message,lat,lon`

### Parameters

This example uses predefined coordinates within the script.

### Request Example

```javascript
// An example script for finding out the distance from the user to multiple points

// Coordinates and name
var coords = [
	{lat: 40.7127837, lon: -74.0059413, name: 'New York, NY'},
	{lat: 34.0522342, lon: -118.2436849, name: 'Los Angeles, CA'},
	{lat: 37.3382082, lon: -121.8863286, name: 'San Jose, CA'},
	{lat: 41.8781136, lon: -87.6297982, name: 'Chicago, IL'},
	{lat: 47.6062095, lon: -122.3320708, name: 'Seattle, WA'},
	];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:json for documentation
var endpoint = 'http://ip-api.com/json/?fields=status,message,lat,lon';

function getDistanceFromLatLonInKm(lat1, lon1, lat2, lon2) {
	var R = 6371; // Radius of the earth in km
	var dLat = deg2rad(lat2-lat1);  // deg2rad below
	var dLon = deg2rad(lon2-lon1); 
	var a = 
		Math.sin(dLat/2) * Math.sin(dLat/2) +
		Math.cos(deg2rad(lat1)) * Math.cos(deg2rad(lat2)) * 
		Math.sin(dLon/2) * Math.sin(dLon/2);
	var c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); 
	var d = R * c; // Distance in km
	return d;
}

function deg2rad(deg) {
	return deg * (Math.PI/180)
}

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Distance in kilometers for each coordinate
		for(var i = 0; i < coords.length; i++) {
			var diff = getDistanceFromLatLonInKm(coords[i].lat, coords[i].lon, response.lat, response.lon);
			console.log('distance to ' + coords[i].name + ': ' + diff + 'km');
		}
	}
};
xhr.open('GET', endpoint, true);
xhr.send();
```

### Response Example (Success)

```json
{
  "status": "success",
  "message": "private range",
  "lat": 37.7749,
  "lon": -122.4194
}
```

### Response Example (Error)

```json
{
  "status": "fail",
  "message": "invalid query string",
  "lat": null,
  "lon": null
}
```
```

--------------------------------

### JSONP Callback Example

Source: https://ip-api.com/docs/api%3Ajson

Shows how to receive the response wrapped in a JavaScript callback function for JSONP requests.

```APIDOC
## GET /json/{query}?callback=...

### Description
Enable JSONP by providing a callback function name via the `callback` query parameter. The JSON response will be wrapped within this function call.

### Method
GET

### Endpoint
`http://ip-api.com/json/{query}`

### Query Parameters
- **callback** (string) - Required - The name of the JavaScript function to wrap the JSON response.

### Request Example
```
http://ip-api.com/json/24.48.0.1?callback=handleGeoData
```

### Response Example
```javascript
handleGeoData({
  "query": "24.48.0.1",
  "status": "success",
  "country": "Canada",
  "countryCode": "CA",
  "region": "QC",
  "regionName": "Quebec",
  "city": "Montreal",
  "zip": "H1K",
  "lat": 45.6085,
  "lon": -73.5493,
  "timezone": "America/Toronto",
  "isp": "Le Groupe Videotron Ltee",
  "org": "Videotron Ltee",
  "as": "AS5769 Videotron Ltee"
});
```
```

--------------------------------

### Custom Fields Example

Source: https://ip-api.com/docs/api%3Ajson

Demonstrates how to request specific fields using the `fields` query parameter.

```APIDOC
## GET /json/{query}?fields=...

### Description
This example shows how to request a subset of the available data fields using the `fields` query parameter. You can specify fields by name (comma-separated) or by a numeric bitmask.

### Method
GET

### Endpoint
`http://ip-api.com/json/{query}`

### Query Parameters
- **fields** (string) - Required - A comma-separated list of desired fields (e.g., `status,country,city`) or a numeric bitmask (e.g., `61439`).

### Request Example (Field Names)
```
http://ip-api.com/json/?fields=status,message,country,countryCode,region,regionName,city,zip,lat,lon,timezone,isp,org,as,query
```

### Request Example (Numeric Bitmask)
```
http://ip-api.com/json/?fields=61439
```

### Response Example (for fields=status,country,city)
```json
{
  "status": "success",
  "country": "United States",
  "city": "Mountain View"
}
```
```

--------------------------------

### API Endpoint Examples

Source: https://ip-api.com/docs/dns

Shows the different ways to call the ip-api.com API. The primary method uses a randomly generated subdomain for EDNS client subnet support, while a secondary method offers automatic redirection.

```http
http://_[32 random alphanumeric characters]_.edns.ip-api.com/json
http://edns.ip-api.com/json
```

--------------------------------

### JavaScript Batch Request Example for ip-api.com

Source: https://ip-api.com/docs/api%3Abatch

This JavaScript code example demonstrates how to perform a batch request to the ip-api.com API to get geolocation data for multiple IP addresses. It uses the XMLHttpRequest object to send a POST request with a JSON array of IPs and logs the results to the console. Ensure the IP list does not exceed 100 addresses.

```javascript
// An example script doing a batch request

// List of IP addresses to query, up to 100
var IPs = ["208.80.152.201", "8.8.8.8", "24.48.0.1"];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:batch for documentation
var endpoint = 'http://ip-api.com/batch';

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if (this.readyState == 4 && this.status == 200) {
		// Result array
		var response = JSON.parse(this.responseText);
		console.log(response);
		response.forEach(function (item) {
			console.log(item.query + " is in " + item.city + ", " + item.country);
		});
	}
};
var data = JSON.stringify(IPs);
console.log("sending:", data);

xhr.open('POST', endpoint, true);
xhr.send(data);
```

--------------------------------

### Example API Response Structure

Source: https://ip-api.com/docs/dns

Illustrates the JSON response format from the ip-api.com API. It includes 'dns' and 'edns' objects detailing IP addresses and geolocation information.

```json
{
    "dns": {
        "ip": "74.125.73.83",
        "geo": "United States - Google"
    },
    "edns": {
        "ip": "91.198.174.0",
        "geo": "Netherlands - Wikimedia Foundation"
    }
}
```

--------------------------------

### GET /json

Source: https://ip-api.com/docs/dns

Retrieve DNS and client geolocation information by sending an HTTP GET request to the specified endpoint. This API is designed to be called from the client's browser.

```APIDOC
## GET /json

### Description
This endpoint returns information about the DNS server used by the client and the client's own IP address and geolocation. It is recommended to call this API from the client's browser to get accurate geolocation data.

### Method
GET

### Endpoint
`http://_[32 random alphanumeric characters]_.edns.ip-api.com/json`
OR
`http://edns.ip-api.com/json` (slower due to automatic redirection)

### Parameters
#### Query Parameters
- **callback** (string) - Optional - Specifies a JSONP callback function name.

### Request Example
`http://edns.ip-api.com/json/?callback=myCallback`

### Response
#### Success Response (200)
- **dns** (object) - Contains IP address and Geolocation of the DNS server.
  - **ip** (string) - The IP address of the DNS server.
  - **geo** (string) - The geolocation of the DNS server (e.g., "United States - Google").
- **edns** (object) - Contains IP address and Geolocation of the client. This field may be absent if the DNS server did not send the client subnet.
  - **ip** (string) - The IP address of the client.
  - **geo** (string) - The geolocation of the client (e.g., "Netherlands - Wikimedia Foundation").

#### Response Example
```json
{
    "dns": {
        "ip": "74.125.73.83",
        "geo": "United States - Google"
    },
    "edns": {
        "ip": "91.198.174.0",
        "geo": "Netherlands - Wikimedia Foundation"
    }
}
```

### Caching
Results are cached for 60 seconds. Expired results may redirect to a new, randomly generated domain.
```

--------------------------------

### JavaScript: Calculate distance from user to multiple points

Source: https://ip-api.com/docs/api%3Ajson

This JavaScript example calculates the distance in kilometers from the user's current location to a predefined list of geographical points. It fetches the user's latitude and longitude using the ip-api.com API and then uses a Haversine formula implementation to compute the distances. The `coords` array should contain the latitude, longitude, and name of the target locations.

```javascript
// An example script for finding out the distance from the user to multiple points

// Coordinates and name
var coords = [
	{lat: 40.7127837, lon: -74.0059413, name: 'New York, NY'},
	{lat: 34.0522342, lon: -118.2436849, name: 'Los Angeles, CA'},
	{lat: 37.3382082, lon: -121.8863286, name: 'San Jose, CA'},
	{lat: 41.8781136, lon: -87.6297982, name: 'Chicago, IL'},
	{lat: 47.6062095, lon: -122.3320708, name: 'Seattle, WA'},
	];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:json for documentation
var endpoint = 'http://ip-api.com/json/?fields=status,message,lat,lon';

function getDistanceFromLatLonInKm(lat1, lon1, lat2, lon2) {
	var R = 6371; // Radius of the earth in km
	var dLat = deg2rad(lat2-lat1);  // deg2rad below
	var dLon = deg2rad(lon2-lon1); 
	var a = 
		Math.sin(dLat/2) * Math.sin(dLat/2) +
		Math.cos(deg2rad(lat1)) * Math.cos(deg2rad(lat2)) * 
		Math.sin(dLon/2) * Math.sin(dLon/2);
	var c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); 
	var d = R * c; // Distance in km
	return d;
}

function deg2rad(deg) {
	return deg * (Math.PI/180)
}

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Distance in kilometers for each coordinate
		for(var i = 0; i < coords.length; i++) {
			var diff = getDistanceFromLatLonInKm(coords[i].lat, coords[i].lon, response.lat, response.lon);
			console.log('distance to ' + coords[i].name + ': ' + diff + 'km');
		}
	}
};
xhr.open('GET', endpoint, true);
xhr.send();

```

--------------------------------

### GET /xml/{query}

Source: https://ip-api.com/docs/api%3Axml

Retrieves geolocation data for a given IP address or domain name in XML format. If no query is provided, it uses the current IP address.

```APIDOC
## GET /xml/{query}

### Description
Retrieves geolocation data for a given IP address or domain name in XML format. If no query is provided, it uses the current IP address.

### Method
GET

### Endpoint
`http://ip-api.com/xml/{query}`

### Parameters
#### Path Parameters
- **query** (string) - Optional - An IPv4/IPv6 address or a domain name. If omitted, the current IP address is used.

#### Query Parameters
- **fields** (string) - Optional - A comma-separated list of fields to include in the response, or a numeric value representing a combination of fields.
- **lang** (string) - Optional - The language for localized city, regionName, and country fields. Supported values: en, de, es, pt-BR, fr, ja, zh-CN, ru.

### Request Example
```
http://ip-api.com/xml/24.48.0.1
```

### Response
#### Success Response (200)
- **status** (string) - Indicates whether the query was successful ('success') or failed ('fail').
- **country** (string) - Country name.
- **countryCode** (string) - Two-letter country code (ISO 3166-1 alpha-2).
- **region** (string) - Region/state short code.
- **regionName** (string) - Region/state name.
- **city** (string) - City name.
- **zip** (string) - Zip code.
- **lat** (float) - Latitude coordinate.
- **lon** (float) - Longitude coordinate.
- **timezone** (string) - Timezone identifier (tz).
- **isp** (string) - Internet Service Provider name.
- **org** (string) - Organization name.
- **as** (string) - Autonomous System number and organization.
- **query** (string) - The IP address used for the query.

#### Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<query>
  <status>success</status>
  <country>Canada</country>
  <countryCode>CA</countryCode>
  <region>QC</region>
  <regionName>Quebec</regionName>
  <city>Montreal</city>
  <zip>H1K</zip>
  <lat>45.6085</lat>
  <lon>-73.5493</lon>
  <timezone>America/Toronto</timezone>
  <isp>Le Groupe Videotron Ltee</isp>
  <org>Videotron Ltee</org>
  <as>AS5769 Videotron Ltee</as>
  <query>24.48.0.1</query>
</query>
```

#### Error Response (e.g., 400 or other applicable codes)
- **status** (string) - 'fail'
- **message** (string) - Description of the error (e.g., 'private range', 'reserved range', 'invalid query').

#### Error Response Example
```xml
<?xml version="1.0" encoding="UTF-8"?>
<query>
  <status>fail</status>
  <message>invalid query</message>
</query>
```

### Usage Limits
- **45 requests per minute** per IP address.
- Exceeding the limit will result in throttling (HTTP 429).
- Persistent violations may lead to a temporary IP ban.
- Check `X-Rl` header for remaining requests and `X-Ttl` for reset time.

### Notes
- No API key is required.
- SSL (HTTPS) is not available for the free API.
```

--------------------------------

### GET /json/{query}

Source: https://ip-api.com/docs/api%3Ajson

Retrieve geolocation data for a specified IP address or domain. If no query is provided, the API will use the current IP address.

```APIDOC
## GET /json/{query}

### Description
Retrieves detailed geolocation information for a given IP address or domain name. If the `{query}` is omitted, the API defaults to the client's current IP address.

### Method
GET

### Endpoint
`http://ip-api.com/json/{query}`

### Parameters
#### Path Parameters
- **query** (string) - Required - The IPv4/IPv6 address or domain name to query.

#### Query Parameters
- **fields** (string) - Optional - Specifies which response fields to include, comma-separated (e.g., `fields=status,country,city`). Can also be a numeric value representing a bitmask of fields.
- **lang** (string) - Optional - Sets the language for localized city, regionName, and country fields. See Localization section for available codes.
- **callback** (string) - Optional - Wraps the JSON response in a JavaScript callback function (JSONP).

### Request Example
```
http://ip-api.com/json/24.48.0.1
```

### Response
#### Success Response (200)
- **status** (string) - Indicates if the query was successful ('success' or 'fail').
- **country** (string) - The name of the country.
- **countryCode** (string) - The two-letter ISO 3166-1 alpha-2 country code.
- **regionName** (string) - The name of the region or state.
- **city** (string) - The name of the city.
- **lat** (float) - The latitude coordinate.
- **lon** (float) - The longitude coordinate.
- **timezone** (string) - The IANA timezone name.
- **isp** (string) - The Internet Service Provider's name.
- **query** (string) - The IP address used for the query.

#### Response Example
```json
{
  "query": "24.48.0.1",
  "status": "success",
  "country": "Canada",
  "countryCode": "CA",
  "region": "QC",
  "regionName": "Quebec",
  "city": "Montreal",
  "zip": "H1K",
  "lat": 45.6085,
  "lon": -73.5493,
  "timezone": "America/Toronto",
  "isp": "Le Groupe Videotron Ltee",
  "org": "Videotron Ltee",
  "as": "AS5769 Videotron Ltee"
}
```

#### Error Response (e.g., 200 with status 'fail')
- **status** (string) - 'fail'.
- **message** (string) - A message explaining the failure (e.g., 'invalid query', 'private range').

#### Error Response Example
```json
{
  "query": "192.168.1.1",
  "status": "fail",
  "message": "private range"
}
```
```

--------------------------------

### GET /line/{query}

Source: https://ip-api.com/docs/api%3Anewline_separated

Retrieves geolocation data for a given IP address or domain name. If no query is provided, it uses the current IP address.

```APIDOC
## GET /line/{query}

### Description
Retrieves geolocation data for a given IP address or domain name. If no query is provided, it uses the current IP address.

### Method
GET

### Endpoint
`http://ip-api.com/line/{query}`

### Parameters
#### Path Parameters
- **query** (string) - Optional - An IPv4/IPv6 address or a domain name. If omitted, the current IP address is used.

#### Query Parameters
- **fields** (string) - Optional - Specifies which response fields to return. Can be a comma-separated list of field names or a numeric code.
- **lang** (string) - Optional - Sets the language for localized city, regionName, and country fields. Supported values: en, de, es, pt-BR, fr, ja, zh-CN, ru.

### Request Example
```
http://ip-api.com/line/8.8.8.8
```

### Response
#### Success Response (200)
- **status** (string) - Indicates 'success' or 'fail'.
- **message** (string) - Included only when status is 'fail'.
- **continent** (string) - Continent name.
- **continentCode** (string) - Two-letter continent code.
- **country** (string) - Country name.
- **countryCode** (string) - Two-letter country code (ISO 3166-1 alpha-2).
- **region** (string) - Region/state short code (FIPS or ISO).
- **regionName** (string) - Region/state name.
- **city** (string) - City name.
- **district** (string) - District (subdivision of city).
- **zip** (string) - Zip code.
- **lat** (float) - Latitude coordinate.
- **lon** (float) - Longitude coordinate.
- **timezone** (string) - Timezone (tz).
- **offset** (int) - Timezone UTC DST offset in seconds.
- **currency** (string) - National currency.
- **isp** (string) - Internet Service Provider name.
- **org** (string) - Organization name.
- **as** (string) - AS number and organization.
- **asname** (string) - AS name.
- **reverse** (string) - Reverse DNS of the IP.
- **mobile** (bool) - Indicates if the connection is mobile.
- **proxy** (bool) - Indicates if the connection is a proxy, VPN, or Tor exit node.
- **hosting** (bool) - Indicates if the IP is associated with hosting or a data center.
- **query** (string) - The IP address used for the query.

#### Response Example
```
success
Canada
CA
QC
Quebec
Montreal
H1K
45.6085
-73.5493
America/Toronto
Le Groupe Videotron Ltee
Videotron Ltee
AS5769 Videotron Ltee
24.48.0.1
```

### Error Handling
- **invalid query**: The provided query is not a valid IP address or domain name.
- **private range**: The IP address belongs to a private IP range.
- **reserved range**: The IP address belongs to a reserved IP range.

### Usage Limits
- **45 requests per minute** from a single IP address.
- Exceeding the limit results in `HTTP 429 Too Many Requests`.
- Continuous exceeding may lead to a temporary IP ban (1 hour).
- `X-Rl` header: requests remaining in the current window.
- `X-Ttl` header: seconds until the limit resets.

### Notes
- SSL (HTTPS) is not available for the free API. A pro service is offered for SSL access.
- Commercial use is not allowed for this endpoint. Please see the pro service for commercial support.
```

--------------------------------

### GET /csv/{query}

Source: https://ip-api.com/docs/api%3Acsv

Retrieve geolocation data for a specified IP address or domain name. If no query is provided, it defaults to the current IP address.

```APIDOC
## GET /csv/{query}

### Description
Retrieves geolocation data in CSV format for a given IP address or domain name. If `query` is omitted, the API uses the client's current IP address.

### Method
GET

### Endpoint
`http://ip-api.com/csv/{query}`

### Parameters
#### Path Parameters
- **query** (string) - Optional - An IPv4/IPv6 address or a domain name.

#### Query Parameters
- **fields** (string) - Optional - Comma-separated list of fields to include in the response. Can also be a numeric code representing a predefined set of fields.
- **lang** (string) - Optional - Language for localized city, regionName, and country fields. Supported values: en, de, es, pt-BR, fr, ja, zh-CN, ru.
- **header** (boolean) - Optional - Set to `true` to include a field header in the response.

### Request Example
```
http://ip-api.com/csv/1.1.1.1?fields=status,country,city
```

### Response
#### Success Response (200)
- **status** (string) - 'success' or 'fail'.
- **country** (string) - Country name.
- **city** (string) - City name.
- **query** (string) - The IP address or domain name used for the query.
- ... (other fields as specified by the `fields` parameter)

#### Response Example
```csv
success,Australia,Sunshine
```

### Error Handling
- **status: fail** - If the query is invalid or a reserved range.
  - **message** (string) - Reason for failure (e.g., 'invalid query', 'private range').

### Usage Limits
- **Requests per minute**: 45 per IP address.
- **Rate Limiting**: `HTTP 429` is returned if the limit is exceeded. Headers `X-Rl` (requests remaining) and `X-Ttl` (time until reset) are provided.

### Notes
- No API key is required.
- SSL (HTTPS) is not available for the free service.
- Commercial use is not allowed; refer to the pro service for commercial support.
```

--------------------------------

### Usage Limits and Best Practices

Source: https://ip-api.com/docs/api%3Ajson

Details on request limits, throttling, IP bans, and recommended handling of rate limit headers.

```APIDOC
## Usage Limits

This endpoint is limited to **45** requests per minute from an IP address. If you exceed the limit, requests will be throttled (`HTTP 429`) until the rate limit window resets. Continuous exceeding of the limit may result in an IP ban for 1 hour.

### Rate Limit Headers

- `X-Rl`: The number of requests remaining in the current rate limit window.
- `X-Ttl`: The number of seconds until the rate limit window resets.

**Recommendation:** Always check the `X-Rl` header. If it is 0, do not send further requests for the duration specified by `X-Ttl`.

### Commercial Use

Commercial use of this endpoint is not permitted. For commercial needs, please refer to the pro service for SSL access, unlimited queries, and commercial support.
```

--------------------------------

### API Usage

Source: https://ip-api.com/docs/dns

Information on how to test the API using different DNS providers and details on usage limits.

```APIDOC
## API Usage and Limits

### Testing the API

**Test via Google Public DNS:**
```bash
API_HOST=$(</dev/urandom tr -dc a-z0-9|head -c32).edns.ip-api.com; API_IP=$(dig $API_HOST +short @8.8.8.8); curl -H "Host: $API_HOST" http://$API_IP/json
```

**Test via OpenDNS:**
```bash
API_HOST=$(</dev/urandom tr -dc a-z0-9|head -c32).edns.ip-api.com; API_IP=$(dig $API_HOST +short @208.67.222.222); curl -H "Host: $API_HOST" http://$API_IP/json
```

### Callback (JSONP)
By default, no callback function is invoked. You can specify a custom callback function using the `callback` GET parameter.

**Example:** `http://edns.ip-api.com/json/?callback=myCallback`

### Usage Limits
Commercial use of this endpoint is not permitted. For SSL access, unlimited queries, and commercial support, please refer to our pro service.
```

--------------------------------

### Batch IP Query using cURL

Source: https://ip-api.com/docs/api%3Abatch

Demonstrates how to perform a batch query for multiple IP addresses using cURL. It shows a basic request with an array of IP addresses and a more advanced request specifying fields for each query.

```bash
curl http://ip-api.com/batch \
--data '["208.80.152.201", "91.198.174.192"]'
```

```bash
curl http://ip-api.com/batch?fields=isp \
--data '[{"query": "208.80.152.201", "fields": "country"}, "8.8.8.8"]'
```

--------------------------------

### Test API via OpenDNS

Source: https://ip-api.com/docs/dns

A bash script to test the ip-api.com API by querying it through OpenDNS. It generates a random API host, retrieves its IP using 'dig', and then uses 'curl' to make the API request.

```bash
API_HOST=$(</dev/urandom tr -dc a-z0-9|head -c32).edns.ip-api.com; API_IP=$(dig $API_HOST +short @208.67.222.222); curl -H "Host: $API_HOST" http://$API_IP/json
```

--------------------------------

### Test API via Google Public DNS

Source: https://ip-api.com/docs/dns

A bash script to test the ip-api.com API by querying it through Google Public DNS. It generates a random API host, retrieves its IP using 'dig', and then uses 'curl' to make the API request.

```bash
API_HOST=$(</dev/urandom tr -dc a-z0-9|head -c32).edns.ip-api.com; API_IP=$(dig $API_HOST +short @8.8.8.8); curl -H "Host: $API_HOST" http://$API_IP/json
```

--------------------------------

### POST /batch

Source: https://ip-api.com/docs/api%3Abatch

Query multiple IP addresses in a single HTTP request. This is significantly faster than submitting individual queries. Supports custom fields and response language.

```APIDOC
## POST /batch

### Description
Allows querying multiple IP addresses in a single HTTP request, which is significantly faster than individual queries. Supports custom fields and response language.

### Method
POST

### Endpoint
`http://ip-api.com/batch`

### Parameters
#### Query Parameters
- **fields** (string) - Optional - Specifies the response fields to include. Example: `fields=isp,country`
- **lang** (string) - Optional - Specifies the response language. Example: `lang=ru`

#### Request Body
The request body must be a JSON array containing up to 100 IP addresses or objects. Each element can be:
- A string representing an IPv4/IPv6 address.
- An object with the following structure:
  - **query** (string) - Required - The IPv4/IPv6 address.
  - **_fields_** (string) - Optional - Overrides the default `fields` query parameter for this specific query.
  - **_lang_** (string) - Optional - Overrides the default `lang` query parameter for this specific query.

`HTTP 422 Unprocessable Entity` will be returned for requests containing more than 100 entries.

### Request Example
```json
[
  "208.80.152.201",
  "91.198.174.192",
  {
    "query": "8.8.8.8",
    "fields": "isp,country",
    "lang": "ru"
  }
]
```

### Response
#### Success Response (200)
Returns a JSON array where each element corresponds to the queried IP address or object. The structure of each element depends on the requested fields.

**Example Response Structure:**
```json
[
  {
    "country": "США",
    "countryCode": "US",
    "city": "Сан-Франциско",
    "query": "208.80.152.201"
  },
  {
    "status": "success",
    "country": "United States",
    "countryCode": "US",
    "region": "VA",
    "regionName": "Virginia",
    "city": "Ashburn",
    "zip": "20149",
    "lat": 39.03,
    "lon": -77.5,
    "timezone": "America/New_York",
    "isp": "Google LLC",
    "org": "Google Public DNS",
    "as": "AS15169 Google LLC",
    "query": "8.8.8.8"
  }
]
```

#### Error Response (422)
- **status** (string) - `fail`
- **message** (string) - Error message, e.g., "Invalid request" or "Batch too large."

```

--------------------------------

### JavaScript: Redirect users based on country code

Source: https://ip-api.com/docs/api%3Ajson

This JavaScript snippet demonstrates how to redirect users to different websites based on their country code. It uses the ip-api.com JSON endpoint to fetch the country code and then performs the redirection using `window.location.replace()`. Ensure the `endpoint` variable correctly points to the ip-api.com JSON endpoint with the required `fields` parameter.

```javascript
// An example script for redirecting users from USA to https://google.com/
// and users from Canada to https://google.ca/

// ip-api endpoint URL
// we need only the countryCode, but you can request more fields
// see http://ip-api.com/docs/api:json for documentation
var endpoint = 'http://ip-api.com/json/?fields=status,message,countryCode';

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if (this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Redirect
		if(response.countryCode == "US") {
			window.location.replace("https://google.com/");
		}
		if(response.countryCode == "CA") {
			window.location.replace("https://google.ca/");
		}
	}
};
xhr.open('GET', endpoint, true);
xhr.send();

```

--------------------------------

### Batch IP Query Request Structure

Source: https://ip-api.com/docs/api%3Abatch

Illustrates the JSON structure for building a batch IP query request. The array can contain simple IP address strings or objects with 'query', optional '_fields_', and optional '_lang_' properties.

```json
[
    "208.80.152.201",
    "8.8.8.8",
    "24.48.0.1"
]
```

```json
[
    {
        "query": "208.80.152.201",
        "_fields_": "city,country,countryCode,query",
        "_lang_": "ru"
    },
    "8.8.8.8",
    "24.48.0.1"
]
```

--------------------------------

### Batch API

Source: https://ip-api.com/docs/index

Allows querying multiple IP addresses in a single HTTP request to optimize performance. Supports JSON response format.

```APIDOC
## POST /batch

### Description
Queries multiple IP addresses in one HTTP request. Ideal for reducing the number of requests when you need data for many IPs.

### Method
POST

### Endpoint
/batch

### Parameters
#### Request Body
- **ips** (array of strings) - Required - An array of IP addresses to query.

### Request Example
```json
{
    "ips": [
        "8.8.8.8",
        "1.1.1.1",
        "9.9.9.9"
    ]
}
```

### Response
#### Success Response (200)
- **result** (array of objects) - An array containing the geolocation data for each queried IP address.

#### Response Example
```json
{
    "result": [
        {
            "ip": "8.8.8.8",
            "country": "United States",
            "countryCode": "US",
            "region": "ca",
            "regionName": "California",
            "city": "Mountain View",
            "zip": "94043",
            "lat": 37.4056,
            "lon": -122.0775,
            "timezone": "America/Los_Angeles",
            "isp": "Google LLC",
            "org": "Google LLC",
            "as": "AS15169 Google LLC"
        },
        {
            "ip": "1.1.1.1",
            "country": "United States",
            "countryCode": "US",
            "region": "nj",
            "regionName": "New Jersey",
            "city": "Edison",
            "zip": "08837",
            "lat": 40.5588,
            "lon": -74.3968,
            "timezone": "America/New_York",
            "isp": "Cloudflare, Inc.",
            "org": "Cloudflare, Inc.",
            "as": "AS13335 Cloudflare, Inc."
        }
    ]
}
```
```

--------------------------------

### DNS API

Source: https://ip-api.com/docs/index

Retrieves the Client Subnet (edns-client-subnet) and DNS Server information. Supports JSON response format.

```APIDOC
## GET /dns

### Description
Retrieves the Client Subnet (edns-client-subnet) and the DNS Server that responded to the request.

### Method
GET

### Endpoint
/dns

### Parameters
No parameters required.

### Request Example
```
GET /dns
```

### Response
#### Success Response (200)
- **ip** (string) - The IP address of the client making the request.
- **dns** (string) - The IP address of the DNS server that responded.

#### Response Example
```json
{
    "ip": "192.0.2.1",
    "dns": "198.51.100.5"
}
```
```

--------------------------------

### Fetch IP Geolocation Data using Batch Request (PHP)

Source: https://ip-api.com/docs/api%3Abatch

This PHP script demonstrates how to perform a batch request to the ip-api.com API to retrieve geolocation data for multiple IP addresses. It sends a POST request with a JSON-encoded array of IP addresses to the batch endpoint and then decodes and prints the JSON response.

```php
<?php
// An example script doing a batch request

// List of IP addresses to query, up to 100
$ips = ['208.80.152.201', '8.8.8.8', '24.48.0.1'];

// ip-api endpoint URL
// see http://ip-api.com/docs/api:batch for documentation
$endpoint = 'http://ip-api.com/batch';

$options = [
	'http' => [
		'method' => 'POST',
		'user_agent' => 'Batch-Example/1.0',
		'header' => 'Content-Type: application/json',
		'content' => json_encode($ips)
	]
];
$response = file_get_contents($endpoint, false, stream_context_create($options));

// Decode the response and print it
$array = json_decode($response, true);
print_r($array);
?>
```

--------------------------------

### Geolocation API

Source: https://ip-api.com/docs/index

Allows querying IP address information such as country, region, city, coordinates, etc. Supports JSON, XML, CSV, Newline, and PHP response formats.

```APIDOC
## GET /json/{ip_address}

### Description
Retrieves geolocation data for a given IP address in JSON format.

### Method
GET

### Endpoint
/json/{ip_address}

### Parameters
#### Path Parameters
- **ip_address** (string) - Required - The IP address to query.

### Request Example
```
GET /json/8.8.8.8
```

### Response
#### Success Response (200)
- **ip** (string) - The queried IP address.
- **country** (string) - The country name.
- **countryCode** (string) - The two-character country code.
- **region** (string) - The region name.
- **regionName** (string) - The name of the region.
- **city** (string) - The city name.
- **zip** (string) - The zip code.
- **lat** (number) - The latitude.
- **lon** (number) - The longitude.
- **timezone** (string) - The timezone of the location.
- **isp** (string) - The Internet Service Provider.
- **org** (string) - The organization name.
- **as** (string) - The Autonomous System number and name.

#### Response Example
```json
{
    "ip": "8.8.8.8",
    "country": "United States",
    "countryCode": "US",
    "region": "ca",
    "regionName": "California",
    "city": "Mountain View",
    "zip": "94043",
    "lat": 37.4056,
    "lon": -122.0775,
    "timezone": "America/Los_Angeles",
    "isp": "Google LLC",
    "org": "Google LLC",
    "as": "AS15169 Google LLC"
}
```
```
Tokens:
Raw