Options

Using the IPstack API's output parameter the API result format can be switched between JSON (default) and XML. Set the output parameter to json or xml depending on your preference.

Requesting JSON Format

https://api.apilayer.net/ipstack/134.201.250.155?access_key=YOUR_ACCESS_KEY&output=json

Requesting XML Format

https://api.apilayer.net/ipstack/134.201.250.155?access_key=YOUR_ACCESS_KEY&output=xml

To see the API response, navigate to the API Response section.

Specify Response Fields

To save bandwidth and speed up response times, the IPstack API's fields parameter can be used to limit API results to a certain object or set of objects.

This parameter is supported by all 3 API endpoints. To use this feature, append the fields parameter to your API request URL and specify one of the following options:

fields = main // returns main API objects from "ip" to "longitude"

fields = country_code // returns only the "country_code" object

fields = location // returns the entire "location" object with sub-objects
fields = location.capital // returns only the "capital" object inside "location"

fields = country_code,location.capital // returns both the "country_code" and the "capital" object

Example Request:

Setting the fields object to country_code causes the IPstack API to return only the country_code object.

https://api.apilayer.net/ipstack/134.201.250.155?access_key=YOUR_ACCESS_KEY&fields=country_code

Example Response:

{
  "country_code": "US"
}

Important: Please note that modules not supported by your subscription plan (e.g. time_zone on the Free Plan) will cause error 301 to be returned by the API. The same error will be shown when trying to access the Security Module without having set &security=1 in the API request.

Specify Response Language

The IPstack API is capable of delivering its result set in different languages. To request data in a language other than English (default), append the API's language parameter to your API request URL and set it to one of the supported 2-letter language codes.

Supported languages

en - English/US
de - German
es - Spanish
fr - French
ja - Japanese
pt-br - Portugues (Brazil)
ru - Russian
zh - Chinese

Example Request: In the following example request, the language is set to de for German.

https://api.apilayer.net/ipstack/134.201.250.155?access_key=YOUR_ACCESS_KEY&language=de

Example Response: The API now responds in German.

{
    "ip": "134.201.250.155",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "Nordamerika", // translated
    "country_code": "US",
    "country_name": "United States",
    "region_code": "CA",
    "region_name": "Kalifornien", // translated
    "city": "Los Angeles",
    "zip": "90013",
    "latitude": 34.0655,
    "longitude": -118.2405,
    "msa": "31100",
    "dma": "803",
    "radius": null,
    "ip_routing_type": null,
    "connection_type": null,
    "location": { ... },
    "time_zone": { ... },
    "currency": { ... },
    "connection": { ... },
}

Please note that certain objects may not be subject to translation.

Enable Security Module

Customers subscribed to the Professional Plus Plan may access the IPstack API's Security Module, which can be used to assess risks and threats originating from certain IP addresses before any harm can be done to a website or web application.

In order to use this feature, append the API's security parameter and set it to 1.

Example Request:

https://api.apilayer.net/ipstack/103.3.61.114?access_key=YOUR_ACCESS_KEY&security=1

Example Response: If the Security Module is supported by your subscription plan, the API response will now contain a security object. For illustration purposes the IP address 103.3.61.114, which is known to be used by the Tor system, has been used for this example API request.

[...]
  "security": {
    "is_proxy": false,
    "proxy_type": null,
    "is_crawler": false,
    "crawler_name": null,
    "crawler_type": null,
    "is_tor": true,
    "threat_level": "high",
    "threat_types": [
        "tor"
    ],
    "proxy_last_detected": null,
    "proxy_level": null,
    "vpn_service": null,
    "anonymizer_status": null,
    "hosting_facility": false
  }
[...]

Enable Hostname Lookup

By default, the IPstack API does not return information about the hostname the given IP address resolves to. In order to include the hostname object in your API result, append the API's hostname parameter and set it to 1.

Example Request:

https://api.apilayer.net/ipstack/160.39.144.19?access_key=YOUR_ACCESS_KEY&hostname=1

Example Response: If Hostname Lookup is enabled, the API response will now come with a hostname object containing the given hostname value.

{
  "ip": "160.39.144.19",
  "hostname": "dyn-160-39-144-19.dyn.columbia.edu",
  [...]
}

Important: Hostname Lookup is disabled by default to reduce bandwidth. Please note that enabling Hostname Lookup may increase API response times.