ipstack API

Getting Started

API Access Key

Your API Access Key is your unique authentication key used to gain access to the ipstack API. In order to authenticate with the API, append the access_key parameter to the API's base URL and set it to your access key value.

Base URL:

https://api.ipstack.com/

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY

API Response

The ipstack API is capable of delivering data either in JSON format (default) or XML format. Find below the API result ipstack would return in response to the API call shown in the section above, which queries the API for the IP address 134.201.250.155.

{
  "ip": "134.201.250.155",
  "hostname": "134.201.250.155",
  "type": "ipv4",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "CA",
  "region_name": "California",
  "city": "Los Angeles",
  "zip": "90013",
  "latitude": 34.0453,
  "longitude": -118.2413,
  "location": {
    "geoname_id": 5368361,
    "capital": "Washington D.C.",
    "languages": [
        {
          "code": "en",
          "name": "English",
          "native": "English"
        }
    ],
    "country_flag": "https://assets.ipstack.com/images/assets/flags_svg/us.svg",
    "country_flag_emoji": "🇺🇸",
    "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "calling_code": "1",
    "is_eu": false
  },
  "time_zone": {
    "id": "America/Los_Angeles",
    "current_time": "2018-03-29T07:35:08-07:00",
    "gmt_offset": -25200,
    "code": "PDT",
    "is_daylight_saving": true
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "plural": "US dollars",
    "symbol": "$",
    "symbol_native": "$"
  },
  "connection": {
    "asn": 25876,
    "isp": "Los Angeles Department of Water & Power"
  },
  "security": {
    "is_proxy": false,
    "proxy_type": null,
    "is_crawler": false,
    "crawler_name": null,
    "crawler_type": null,
    "is_tor": false,
    "threat_level": "low",
    "threat_types": null
  }
}
<result>
  <ip>134.201.250.155</ip>
  <hostname>134.201.250.155</hostname>
  <type>ipv4</type>
  <continent_code>NA</continent_code>
  <continent_name>North America</continent_name>
  <country_code>US</country_code>
  <country_name>United States</country_name>
  <region_code>CA</region_code>
  <region_name>California</region_name>
  <city>Los Angeles</city>
  <zip>90013</zip>
  <latitude>34.0453</latitude>
  <longitude>-118.2413</longitude>
  <location>
    <geoname_id>5368361</geoname_id>
    <capital>Washington D.C.</capital>
    <languages>
      <code>en</code>
      <name>English</name>
      <native>English</native>
    </languages>
    <country_flag>https://assets.ipstack.com/images/assets/flags_svg/us.svg</country_flag>
    <country_flag_emoji>🇺🇸</country_flag_emoji>
    <country_flag_emoji_unicode>U+1F1FA U+1F1F8</country_flag_emoji_unicode>
    <calling_code>1</calling_code>
    <is_eu/>
  </location>
  <time_zone>
    <id>America/Los_Angeles</id>
    <current_time>2018-03-29T07:53:46-07:00</current_time>
    <gmt_offset>-25200</gmt_offset>
    <code>PDT</code>
    <is_daylight_saving>1</is_daylight_saving>
  </time_zone>
  <currency>
    <code>USD</code>
    <name>US Dollar</name>
    <plural>US dollars</plural>
    <symbol>$</symbol>
    <symbol_native>$</symbol_native>
  </currency>
  <connection>
    <asn>25876</asn>
    <isp>Los Angeles Department of Water & Power</isp>
  </connection>
  <security>
    <is_proxy/>
    <proxy_type/>
    <is_crawler/>
    <crawler_name/>
    <crawler_type/>
    <is_tor/>
    <threat_level>low</threat_level>
    <threat_types/>
  </security>
</result>
JSONXML

API responses come with comprehensive location-related data, currency-related data, timezone-related data, connection-related data and security-related data. Throughout the Response Objects section you will learn more about the given response structure and its objects.

Please note: For illustration purposes we have included both Hostname Lookup and the Security Module in the above API response. Please refer to the sections Hostname Lookup and Security Module for details.

Available Endpoints

The ipstack API offers 3 different endpoints, each accepting a different set of parameters and returning different results. Click on the headings below to jump to the respective endpoint's description.

• Standard LookupLook up the data behind an IP address.
• Bulk LookupLook up the data behind multiple IP addresses at once.
• Requester LookupLook up the data behind the IP address your API request is coming from.

Connecting via HTTPS

All premium subscription plans available for the ipstack API come with support for 256-bit SSL encryption. To connect to the API via HTTPS, simply use the https protocol instead of standard http.

JSONP Callbacks

The ipstack API supports JSONP Callbacks, enabling you to enter a function name and cause the API to return your requested API result wrapped inside that function. In order to specify a callback, pass a function name into the API's callback GET parameter.

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & callback = MY_FUNCTION

MY_FUNCTION (
  {
    "ip": "134.201.250.155",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "CA",
    [...]
  }
)JSON ONLY

Error Codes

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Example Error: The following error is returned if your monthly API request volume has been exceeded.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "monthly_limit_reached",
    "info": "Your monthly API request volume has been reached. Please upgrade your plan."
  }
}

Other Errors:

Endpoints

Standard IP Lookup

The ipstack's primary endpoint is called Standard Lookup and is used to look up single IPv4 or IPv6 addresses. To call this endpoint, simply attach any IPv4 or IPv6 address to the API's base URL.

API Request:

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

API Response:

{
  "ip": "134.201.250.155",
  "type": "ipv4",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "CA",
  "region_name": "California",
  "city": "Los Angeles",
  "zip": "90013",
  "latitude": 34.0453,
  "longitude": -118.2413,
  "location": {
    "geoname_id": 5368361,
    "capital": "Washington D.C.",
    "languages": [
        {
          "code": "en",
          "name": "English",
          "native": "English"
        }
    ],
    "country_flag": "https://assets.ipstack.com/images/assets/flags_svg/us.svg",
    "country_flag_emoji": "🇺🇸",
    "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "calling_code": "1",
    "is_eu": false
  },
  "time_zone": {
    "id": "America/Los_Angeles",
    "current_time": "2018-03-29T07:35:08-07:00",
    "gmt_offset": -25200,
    "code": "PDT",
    "is_daylight_saving": true
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "plural": "US dollars",
    "symbol": "$",
    "symbol_native": "$"
  },
  "connection": {
    "asn": 25876,
    "isp": "Los Angeles Department of Water & Power"
  }
}
<result>
  <ip>134.201.250.155</ip>
  <type>ipv4</type>
  <continent_code>NA</continent_code>
  <continent_name>North America</continent_name>
  <country_code>US</country_code>
  <country_name>United States</country_name>
  <region_code>CA</region_code>
  <region_name>California</region_name>
  <city>Los Angeles</city>
  <zip>90013</zip>
  <latitude>34.0453</latitude>
  <longitude>-118.2413</longitude>
  <location>
    <geoname_id>5368361</geoname_id>
    <capital>Washington D.C.</capital>
    <languages>
      <code>en</code>
      <name>English</name>
      <native>English</native>
    </languages>
    <country_flag>https://assets.ipstack.com/images/assets/flags_svg/us.svg</country_flag>
    <country_flag_emoji>🇺🇸</country_flag_emoji>
    <country_flag_emoji_unicode>U+1F1FA U+1F1F8</country_flag_emoji_unicode>
    <calling_code>1</calling_code>
    <is_eu/>
  </location>
  <time_zone>
    <id>America/Los_Angeles</id>
    <current_time>2018-03-29T07:53:46-07:00</current_time>
    <gmt_offset>-25200</gmt_offset>
    <code>PDT</code>
    <is_daylight_saving>1</is_daylight_saving>
  </time_zone>
  <currency>
    <code>USD</code>
    <name>US Dollar</name>
    <plural>US dollars</plural>
    <symbol>$</symbol>
    <symbol_native>$</symbol_native>
  </currency>
  <connection>
    <asn>25876</asn>
    <isp>Los Angeles Department of Water & Power</isp>
  </connection>
</result>
JSONXML

Response Objects: See the Response Objects section to view detailed descriptions for all API response objects and their values returned by the ipstack API.

Bulk IP Lookup

The ipstack API also offers the ability to request data for multiple IPv4 or IPv6 addresses at the same time. In order to process IP addresses in bulk, simply append multiple comma-separated IP addresses to the API's base URL.

API Request:

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155,72.229.28.185,110.174.165.78
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

API Response:

JSON: The API response for bulk queries will contain one IP data object per requested IP address/domain.

XML: Please note that in XML format the main response object will be <batch></batch> and contain one <result></result> with its respective index number per requested IP address/domain.

[
  {
    "ip": "134.201.250.155",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "CA",
    "region_name": "California",
    "city": "Los Angeles",
    "zip": "90013",
    "latitude": 34.0453,
    "longitude": -118.2413,
    "location": { ... },
    "time_zone": { ... },
    "currency": { ... },
    "connection": { ... },
  },
  {
    "ip": "72.229.28.185",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "NY",
    "region_name": "New York",
    "city": "New York",
    "zip": "10036",
    "latitude": 40.7605,
    "longitude": -73.9933,
    "location": { ... },
    "time_zone": { ... },
    "currency": { ... },
    "connection": { ... },
  },
  {
    "ip": "110.174.165.78",
    "type": "ipv4",
    "continent_code": "OC",
    "continent_name": "Oceania",
    "country_code": "AU",
    "country_name": "Australia",
    "region_code": "NSW",
    "region_name": "New South Wales",
    "city": "Coffs Harbour",
    "zip": "2450",
    "latitude": -30.2963,
    "longitude": 153.1135,
    "location": { ... },
    "time_zone": { ... },
    "currency": { ... },
    "connection": { ... },
  }
]
<batch>
  <result index="0">
    <ip>134.201.250.155</ip>
    <type>ipv4</type>
    <continent_code>NA</continent_code>
    <continent_name>North America</continent_name>
    <country_code>US</country_code>
    <country_name>United States</country_name>
    <region_code>CA</region_code>
    <region_name>California</region_name>
    <city>Los Angeles</city>
    <zip>90013</zip>
    <latitude>34.0453</latitude>
    <longitude>-118.2413</longitude>
    <location> [...] </location>
    <time_zone> [...] </time_zone>
    <currency> [...] </currency>
    <connection> [...] </connection>
  </result>
  <result index="1">
    <ip>72.229.28.185</ip>
    <type>ipv4</type>
    <continent_code>NA</continent_code>
    <continent_name>North America</continent_name>
    <country_code>US</country_code>
    <country_name>United States</country_name>
    <region_code>NY</region_code>
    <region_name>New York</region_name>
    <city>New York</city>
    <zip>10036</zip>
    <latitude>40.7605</latitude>
    <longitude>-73.9933</longitude>
    <location> [...] </location>
    <time_zone> [...] </time_zone>
    <currency> [...] </currency>
    <connection> [...] </connection>
  </result>
  <result index="2">
    <ip>110.174.165.78</ip>
    <type>ipv4</type>
    <continent_code>OC</continent_code>
    <continent_name>Oceania</continent_name>
    <country_code>AU</country_code>
    <country_name>Australia</country_name>
    <region_code>NSW</region_code>
    <region_name>New South Wales</region_name>
    <city>Coffs Harbour</city>
    <zip>2450</zip>
    <latitude>-30.2963</latitude>
    <longitude>153.1135</longitude>
    <location> [...] </location>
    <time_zone> [...] </time_zone>
    <currency> [...] </currency>
    <connection> [...] </connection>
  </result>
</batch>
JSONXML

Response Objects: See the Response Objects section to view detailed descriptions for all API response objects and their values returned by the ipstack API.

Requester IP Lookup

The ipstack API also offers a separate API endpoint capable of detecting the IP address which the current API request is coming from. In order to use this endpoint, simply append check to the API's base URL and specify your preferred optional parameters.

API Request:

Sign Up to Run API Requesthttps://api.ipstack.com/check
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

API Response:

{
  "ip": "155.52.187.7",
  "type": "ipv4",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_name": "United States",
  "region_code": "MA",
  "region_name": "Massachusetts",
  "city": "Boston",
  "zip": "02115",
  "latitude": 42.3424,
  "longitude": -71.0878,
  "location": {
    "geoname_id": 4930956,
    "capital": "Washington D.C.",
    "languages": [
        {
          "code": "en",
          "name": "English",
          "native": "English"
        }
    ],
    "country_flag": "https://assets.ipstack.com/images/assets/flags_svg/us.svg",
    "country_flag_emoji": "🇺🇸",
    "country_flag_emoji_unicode": "U+1F1FA U+1F1F8",
    "calling_code": "1",
    "is_eu": false
  },
  "time_zone": {
    "id": "America/New_York",
    "current_time": "2018-03-30T07:54:25-04:00",
    "gmt_offset": -14400,
    "code": "EDT",
    "is_daylight_saving": true
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "plural": "US dollars",
    "symbol": "$",
    "symbol_native": "$"
  },
  "connection": {
    "asn": 40127,
    "isp": "Longwood Medical and Academic Area (LMA)"
  }
}
<result>
  <ip>155.52.187.7</ip>
  <type>ipv4</type>
  <continent_code>NA</continent_code>
  <continent_name>North America</continent_name>
  <country_code>US</country_code>
  <country_name>United States</country_name>
  <region_code>MA</region_code>
  <region_name>Massachusetts</region_name>
  <city>Boston</city>
  <zip>02115</zip>
  <latitude>42.3424</latitude>
  <longitude>-71.0878</longitude>
  <location>
    <geoname_id>4930956</geoname_id>
    <capital>Washington D.C.</capital>
    <languages>
      <code>en</code>
      <name>English</name>
      <native>English</native>
    </languages>
    <country_flag>https://assets.ipstack.com/images/assets/flags_svg/us.svg</country_flag>
    <country_flag_emoji>🇺🇸</country_flag_emoji>
    <country_flag_emoji_unicode>U+1F1FA U+1F1F8</country_flag_emoji_unicode>
    <calling_code>1</calling_code>
    <is_eu/>
  </location>
  <time_zone>
    <id>America/New_York</id>
    <current_time>2018-03-30T07:54:25-04:00</current_time>
    <gmt_offset>-14400</gmt_offset>
    <code>EDT</code>
    <is_daylight_saving>1</is_daylight_saving>
  </time_zone>
  <currency>
    <code>USD</code>
    <name>US Dollar</name>
    <plural>US dollars</plural>
    <symbol>$</symbol>
    <symbol_native>$</symbol_native>
  </currency>
  <connection>
    <asn>40127</asn>
    <isp>Longwood Medical and Academic Area (LMA)</isp>
  </connection>
</result>
JSONXML

Response Objects: See the Response Objects section to view detailed descriptions for all API response objects and their values returned by the ipstack API.

Response Objects

Depending on your subscription plan and the options you choose for your API request, the ipstack API will respond using a series of different modules and objects. Find below a list of all available API response objects explained.

Scroll left & right to navigate

Options

Specify Output Format

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.

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & output = json

Sign Up to Run API Requesthttps://api.ipstack.com/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

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & fields = country_code

{
  "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

Sign Up to Run API Requesthttps://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & language = de

{
    "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.0453,
    "longitude": -118.2413,
    "location": { ... },
    "time_zone": { ... },
    "currency": { ... },
    "connection": { ... },
}
<result>
    <ip>134.201.250.155</ip>
    <type>ipv4</type>
    <continent_code>NA</continent_code>
    <continent_name>Nordamerika</continent_name>
    <country_code>US</country_code>
    <country_name>United States</country_name>
    <region_code>CA</region_code>
    <region_name>Kalifornien</region_name>
    <city>Los Angeles</city>
    <zip>90013</zip>
    <latitude>34.0453</latitude>
    <longitude>-118.2413</longitude>
    <location> [...] </location>
    <time_zone> [...] </time_zone>
    <currency> [...] </currency>
    <connection> [...] </connection>
  </result>
JSONXML

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.

Sign Up to Run API Requesthttps://api.ipstack.com/103.3.61.114
    ? access_key = YOUR_ACCESS_KEY
    & security = 1

[...]
  "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"
    ]
  }
[...]
[...]
  <security>
    <is_proxy/>
    <proxy_type/>
    <is_crawler/>
    <crawler_name/>
    <crawler_type/>
    <is_tor/>
    <threat_level>low</threat_level>
    <threat_types/>
  </security>
[...]
JSONXML

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.

Sign Up to Run API Requesthttps://api.ipstack.com/160.39.144.19
    ? access_key = YOUR_ACCESS_KEY
    & hostname = 1

{
  "ip": "160.39.144.19",
  "hostname": "dyn-160-39-144-19.dyn.columbia.edu",
  [...]
}
<result>
  <ip>160.39.144.19</ip>
  <hostname>dyn-160-39-144-19.dyn.columbia.edu</type>
  [...]
</result>
JSONXML

Sample Code

PHP (cURL)

Standard Lookup: Find below an example for the Standard Lookup Endpoint using PHP cURL.

// set IP address and API access key
$ip = '134.201.250.155';
$access_key = 'YOUR_ACCESS_KEY';

// Initialize CURL:
$ch = curl_init('https://api.ipstack.com/'.$ip.'?access_key='.$access_key.'');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Store the data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$api_result = json_decode($json, true);

// Output the "capital" object inside "location"
echo $api_result['location']['capital'];

JavaScript (jQuery.ajax)

Standard Lookup: Find below an example for the Standard Lookup Endpoint using jQuery.ajax.

// set endpoint and your access key
var ip = '134.201.250.155'
var access_key = 'YOUR_ACCESS_KEY';

// get the API result via jQuery.ajax
$.ajax({
    url: 'https://api.ipstack.com/' + ip + '?access_key=' + access_key,
    dataType: 'jsonp',
    success: function(json) {

        // output the "capital" object inside "location"
        alert(json.location.capital);

    }
});

Business Continuity - API Overages

Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.

What is an overage?

An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.

Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.

Why does APILayer have overage fees?

Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.

How do I know if I will be charged for overages?

When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.

How will I be charged for my API subscription?

You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.

What happens if I don’t have any overage fees?

In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.

What if I consistently have more API calls than my plan allows?

If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.

I would like to upgrade my plan. How can I do that?

You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.