Ipstack API

Ipstack offers a powerful, real-time IP to geolocation API capable of looking up accurate location data and assessing security threats originating from risky IP addresses. Results are delivered within milliseconds in JSON or XML format. Using the ipstack API you will be able to locate website visitors at first glance and adjust your user experience and application accordingly.

This documentation outlines in detail API features, available options and integration guides in different programming languages.

Quickstart Guide

All registered users (free or paid) can use our Quickstart guide to try out all API functionalities at the click of a button. If you're already a customer, you will be able to go to the Quickstart guide using the button below. If not, you can use the button to quickly set up an account.

Get yourself onboarded on ipstack API and start using it in a fraction of minute.

Step 1: Get API Key

Get a free API access key to start using the ipstack API.

Get free API Access Key

Step 2: Get Started with Postman

You can make use of our Postman collection to start using the ipstack API right away.

Run in postman

Fork collection into your workspace


Step 3: Make your first API call

Ipstack API offers three endpoints:

We recommend you to start with the Standard IP Lookup endpoint as it's primary endpoint. It 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.

Check out all the widely used API calls with the necessary parameters in the Postman Collection.

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.

You can gain access to ipstack API by simpling adding your access_API_key in the based URL as a query parameter. For example,

Base URL:

https://api.ipstack.com/

Append your API Access Key: Here is an example API call illustrating how to authenticate with the ipstack API:

https://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY

API Response

Choosing How You Want Your Data

The ipstack API can give you information in two ways: either in JSON format (which is the default) or in XML format. Below is an example of what the ipstack API would return when you ask it about the IP address 134.201.250.155 using the API call mentioned in the previous section.

{ "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.0655, "longitude": -118.2405, "msa": "31100", "dma": "803", "radius": null, "ip_routing_type": null, "connection_type": null, "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": "2024-06-14T01:45:35-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", "sld": "ladwp", "tld": "com", "carrier": "los angeles department of water & power", "home": null, "organization_type": null, "isic_code": null, "naics_code": null }, "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, "proxy_last_detected": null, "proxy_level": null, "vpn_service": null, "anonymizer_status": null, "hosting_facility": false } }
<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.0655</latitude> <longitude>-118.2405</longitude> <msa>31100</msa> <dma>803</dma> <radius>null</radius> <ip_routing_type>null</ip_routing_type> <connection_type>null</connection_type> <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> <sld>ladwp</sld> <tld>com</tld> <carrier>los angeles department of water & power</carrier> <home>null</home> <organization_type>null</organization_type> <isic_code>null</isic_code> <naics_code>null</naics_code> </connection> <security> <is_proxy/> <proxy_type/> <is_crawler/> <crawler_name/> <crawler_type/> <is_tor/> <threat_level>low</threat_level> <threat_types/> <proxy_last_detected/> <proxy_level/> <vpn_service/> <anonymizer_status/> <hosting_facility/> </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.

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

Adding a Personal Touch with JSONP Callbacks

You can make the ipstack API response even more flexible by using JSONP Callbacks. This allows you to wrap your requested API result inside a function of your choice. To make it happen, just pass the function name into the API's callback parameter when making the request.

Example Request: In our example request we are specifying the function name to be MY_FUNCTION

https://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & callback = MY_FUNCTION

Example Response: Your API response will be wrapped inside your preferred callback 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

Please note: JSONP Callbacks can only be used along with the API's output format being set to json.

Error Codes

If something goes wrong, and the resource you asked for isn't available or an API call fails, the ipstack API will send back a JSON error. This error includes two important things: an error code and a description, helping you figure out what went awry.

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:

Ipstack API error codes are divided into three categories 1xx – informational error, 3xx – a few additional steps are required, 4xx – resource doesn’t exists

Code Type Info
404 404_not_found The requested resource does not exist.
101 missing_access_key No API Key was specified.
101 invalid_access_key No API Key was specified or an invalid API Key was specified.
102 inactive_user The current user account is not active. User will be prompted to get in touch with Customer Support.
103 invalid_api_function The requested API endpoint does not exist.
104 usage_limit_reached The maximum allowed amount of monthly API requests has been reached.
301 invalid_fields One or more invalid fields were specified using the fields parameter.
302 too_many_ips Too many IPs have been specified for the Bulk Lookup Endpoint. (max. 50)
303 batch_not_supported_on_plan The Bulk Lookup Endpoint is not supported on the current subscription plan

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:

https://api.ipstack.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API Access Key.
fields [optional] Set to your preferred output field(s) according to the Specify Output Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable the Security module.
language [optional] Set to a 2-letter language code according to the Specify Output Language section to change output language.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.
output [optional] Set to json or xml to choose between output formats.

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.0655, "longitude": -118.2405, "msa": "31100", "dma": "803", "radius": null, "ip_routing_type": null, "connection_type": null, "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", "sld": "ladwp", "tld": "com", "carrier": "los angeles department of water & power", "home": null, "organization_type": null, "isic_code": null, "naics_code": null } }
<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.0655</latitude> <longitude>-118.2405</longitude> <msa>31100</msa> <dma>803</dma> <radius>null</radius> <ip_routing_type>null</ip_routing_type> <connection_type>null</connection_type> <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> <sld>ladwp</sld> <tld>com</tld> <carrier>los angeles department of water & power</carrier> <home>null</home> <organization_type>null</organization_type> <isic_code>null</isic_code> <naics_code>null</naics_code> </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.



Basic Request:

Use this code snippets to look up single IPv4 or IPv6 addresses.

            
        


Get Hostname:

Add "Hostname" and set to 1 to enable Hostname Lookup.

            



Response Wrapped Inside a Custom Function:

Specify a JSONP callback function name and resposne will be wrapped inside the function name.

            



Response in Different Language:

Set to a 2-letter "language" code according to change the output language.

            



Get Specific Response Fields Only:

Suppose you want to get the Zip code of the IP Address – mention "zip" with the "fields" parameter.

Note: You can mention multiple parameters as well with the "fields" parameter.

            



Get Response in XML:

Mention xml with output parameter to get the response in XML.

            

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:

https://api.ipstack.com/134.201.250.155,72.229.28.185,110.174.165.78
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
IP Addresses [Required] A comma-separated list of IPv4 or IPv6 addresses; you can also enter a domain URLs to have ipstack resolve the domains to their underlying IP addresses. (Maxmium allowed values: 50)
access_key [Required] Your API Access Key.
fields [optional] Set to your preferred output field(s) according to the Specify Output Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable the Security module.
language [optional] Set to a 2-letter language code according to the Specify Output Language section to change output language.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.
output [optional] Set to json or xml to choose between output formats.

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.0655, "longitude": -118.2405, "msa": "31100", "dma": "803", "radius": null, "ip_routing_type": null, "connection_type": null, "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, "msa": "35620", "dma": "501", "radius": null, "ip_routing_type": "fixed", "connection_type": "cable", "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, "msa": null, "dma": null, "radius": "73.03858", "ip_routing_type": "fixed", "connection_type": "dsl", "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.0655</latitude> <longitude>-118.2405,</longitude> <msa>31100</msa> <dma>803</dma> <radius>null</radius> <ip_routing_type>null</ip_routing_type> <connection_type>null</connection_type> <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> <msa>35620</msa> <dma>501</dma> <radius>null</radius> <ip_routing_type>fixed</ip_routing_type> <connection_type>cable</connection_type> <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> <msa>null</msa> <dma>null</dma> <radius>73.03858</radius> <ip_routing_type>fixed</ip_routing_type> <connection_type>dsl</connection_type> <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.



Basic Request:

In order to process IP addresses in bulk, simply append multiple comma-separated IP addresses to the API's base URL.

            


Get Hostname:

Add "Hostname" and set to 1 to enable Hostname Lookup.

            



Response Wrapped Inside a Custom Function:

Specify a JSONP callback function name and resposne will be wrapped inside the function name.

            



Response in Different Language:

Set to a 2-letter "language" code according to change the output language.

            



Get Specific Response Fields Only:

Suppose you want to get the Zip code of the IP Address – mention "zip" with the "fields" parameter.

Note: You can mention multiple parameters as well with the "fields" parameter.

            



Get Response in XML:

Mention xml with output parameter to get the response in XML.

            

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:

https://api.ipstack.com/check
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API Access Key.
fields [optional] Set to your preferred output field(s) according to the Specify Output Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable the Security module.
language [optional] Set to a 2-letter language code according to the Specify Output Language section to change output language.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.
output [optional] Set to json or xml to choose between output formats.

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": "02114", "latitude": 42.36235046386719, "longitude": -71.06477355957031, "msa": "14460", "dma": "506", "radius": null, "ip_routing_type": "fixed", "connection_type": "tx", "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": "2024-06-13T09:37:03-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": 40831, "isp": "Mass General Brigham Incorporated", "sld": null, "tld": null, "carrier": "mass general brigham incorporated", "home": false, "organization_type": "Hospital", "isic_code": "Q8610", "naics_code": "000622" } }
<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.3623</latitude> <longitude>-71.0647</longitude> <msa>14460</msa> <dma>506</dma> <radius>null</radius> <ip_routing_type>fixed</ip_routing_type> <connection_type>tx</connection_type> <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> <sld>null</sld> <tld>null</tld> <carrier>mass general brigham incorporated</carrier> <home>false</home> <organization_type>Hospital</organization_type> <isic_code>Q8610</isic_code> <naics_code>000622</naics_code> </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.



Basic Request:

            

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

Response Object Description
ip Returns the requested IP address.
hostname Returns the hostname the requested IP resolves to, only returned if Hostname Lookup is enabled.
type Returns the IP address type IPv4 or IPv6.
continent_code Returns the 2-letter continent code associated with the IP.
View all 2-letter continent codes
continent_name Returns the name of the continent associated with the IP.
country_code Returns the 2-letter country code associated with the IP.
List of all 2-letter country codes
country_name Returns the name of the country associated with the IP.
region_code Returns the region code of the region associated with the IP (e.g. CA for California).
region_name Returns the name of the region associated with the IP.
city Returns the name of the city associated with the IP.
zip Returns the ZIP code associated with the IP.
latitude Returns the latitude value associated with the IP.
longitude Returns the longitude value associated with the IP.
msa Returns Metropolitan Statistical Areas with extensive demographic info defined by the US OMB using Census data
dma Defined Market Areas (DMAs) are codes assigned to geographical regions where the population typically receives similar media.
radius Returns the radius in miles around an IP geolocation where the user is likely to be located.
ip_routing_type It specifies how the connection is routed through the Internet and determines user proximity to the IP address.
ip_routing_type > fixed User connects via fixed-line (e.g., cable, DSL, fiber) and likely near IP location.
ip_routing_type > aol User is part of the AOL network. Country is identifiable in most cases but precise location is not possible.
ip_routing_type > pop User connects via a regional ISP and likely near IP location, possibly across boundaries.
ip_routing_type > satellite User connects via satellite and hence location could be anywhere within the satellite beam, which can span a continent or more.
ip_routing_type > cache proxy User is using a proxy connection. It is possible the user is located in a different country from the IP location
ip_routing_type > cache proxy User is using a proxy connection. It is possible the user is located in a different country from the IP location
ip_routing_type > international proxy User is connecting through a proxy that routes traffic from multiple countries.
ip_routing_type > regional proxy User is connecting through a proxy that routes traffic from multiple states within a single country.
ip_routing_type > corp proxy User connects via a corporate network proxy.
ip_routing_type > mobile gateway User connects mobile devices through a gateway, possibly in a different country.
connection_type How the user connects to the Internet. IPv6 supported.
connection_type > ocx Fiber optic connections (e.g., OC-3, OC-48) used primarily by large backbone carriers.
connection_type > tx Leased lines (e.g., T1, T2, T3, T4) used by many small- and medium-sized companies.
connection_type > consumer satellite High-speed links via satellite.
connection_type > framerelay used as a backup or alternative to T-1.
connection_type > dsl Digital Subscriber Line broadband circuits. Range in speed from 256 Kbps to 20 Mbps.
connection_type > cable Cable modem broadband circuits. Range in speed from 128 Kbps to 100 Mbps.
connection_type > isdn ntegrated Services Digital Network. Provides 128 Kbps speed, with ISDN modems and switches offering 1 Mbps and greater speeds.
connection_type > dialup Consumer dial-up modem technology, which operates at 56 Kbps.
connection_type > fixed wireless Fixed wireless connections (e.g., WDSL, WiMax).
connection_type > mobile wireless Cellular networks (e.g., CDMA, EDGE, 3G, 4G). Speeds vary from 19.2 Kbps to 12 Mbps.
connection_type > unknown low Unknown connection type, low speed.
connection_type > unknown medium Unknown connection type, medium speed.
connection_type > unknown high Unknown connection type, high speed.
location [Object] Returns multiple location-related objects
location > geoname_id Returns the unique geoname identifier in accordance with the Geonames Registry.
location > capital Returns the capital city of the country associated with the IP.
location > languages [Object] Returns an object containing one or multiple sub-objects per language spoken in the country associated with the IP.
location > languages > code Returns the 2-letter language code for the given language.
List of all 2-letter language codes
location > languages > name Returns the name (in the API request's main language) of the given language. (e.g. Portuguese)
location > languages > native Returns the native name of the given language. (e.g. Português)
location > country_flag Returns an HTTP URL leading to an SVG-flag icon for the country associated with the IP.
location > country_flag_emoji Returns the emoji icon for the flag of the country associated with the IP.
location > country_flag_emoji_unicode Returns the unicode value of the emoji icon for the flag of the country associated with the IP. (e.g. U+1F1F5 U+1F1F9 for the Portuguese flag)
location > calling_code Returns the calling/dial code of the country associated with the IP. (e.g. 351) for Portugal.
location > is_eu Returns true or false depending on whether or not the county associated with the IP is in the European Union.
time_zone [Object] Returns an object containing timezone-related data.
time_zone > id Returns the ID of the time zone associated with the IP. (e.g. America/Los_Angeles for PST)
time_zone > current_time Returns the current date and time in the location associated with the IP. (e.g. 2018-03-29T22:31:27-07:00)
time_zone > gmt_offset Returns the GMT offset of the given time zone in seconds. (e.g. -25200 for PST's -7h GMT offset)
time_zone > code Returns the universal code of the given time zone.
List of all available codes
time_zone > is_daylight_saving Returns true or false depending on whether or not the given time zone is considered daylight saving time.
currency [Object] Returns an object containing currency-related data.
currency > code Returns the 3-letter code of the main currency associated with the IP.
Example: USD - List of all available currency codes
currency > name Returns the name of the given currency.
currency > plural Returns the plural name of the given currency.
currency > symbol Returns the symbol letter of the given currency.
currency > symbol_native Returns the native symbol letter of the given currency.
connection [Object] Returns an object containing connection-related data.
connection > asn Returns the Autonomous System Number associated with the IP.
connection > isp Returns the name of the ISP associated with the IP.
connection > sld Returns the name of the second-level domain preceding the top-level domain (e.g., "home" in www.home.neustar).
connection > tld Returns top-level domain, the most general part of a domain (e.g., com, net, edu, country codes).
connection > carrier Returns the name of the organization owning the ASN, responsible for network traffic.
connection > home Indicates if the connection is from a residential network (true/false).
connection > organization_type Classification of the registering organization's type (e.g., Insurance, Banking, Education, etc).
connection > isic_code Returns International Standard Industrial Classification code, Rev. 4, of the organization type.
connection > naics_code Returns North American Industry Classification System code, v2007, of the organization type.
security [Object] Returns an object containing security-related data.
security > is_proxy Returns true or false depending on whether or not the given IP is associated with a proxy.
security > proxy_type Returns the type of proxy the IP is associated with.
View all potential proxy types
security > is_crawler Returns true or false depending on whether or not the given IP is associated with a crawler.
security > crawler_name Returns the name of the crawler the IP is associated with.
security > crawler_type Returns the type of crawler the IP is associated with.
View all potential crawler types
security > is_tor Returns true or false depending on whether or not the given IP is associated with the anonymous Tor system.
security > threat_level Returns the type of threat level the IP is associated with.
View all threat levels
security > threat_types [object] Returns an object containing all threat types associated with the IP.
View all potential threat types
security > anonymizer_status Returns the anonymizing proxy status of an IP address: active, suspect, inactive, or private.
security > anonymizer_status > Active Anonymizer tested positive within the last month.
security > anonymizer_status > Suspect Anonymizer tested positive within the last three months.
security > anonymizer_status > Inactive Anonymizer tested positive within the last six months.
security > anonymizer_status > Private IP addresses with anonymous proxies, usually commercial VPNs, not routinely testable.
security > proxy_last_detected Returns the last detection date of an active anonymizing proxy (format: yyyy-mm-dd). IPv6 supported.
security > proxy_level Returns the degree of IP concealment by the proxy: transparent, anonymous, distorting, or elite.
security > proxy_level > Anonymous
  • Anonymous: Obscures user IP, reveals proxy use.
    1. REMOTE_ADDR = Proxy IP Address
    2. HTTP_VIA = Proxy IP Address
    3. HTTP_X_FORWARDED_FOR = Proxy IP Address
  • security > proxy_level > Distorting
  • Distorting: Obscures user IP, reveals proxy use, shows random IP.
    1. REMOTE_ADDR = Proxy IP Address
    2. HTTP_VIA = Proxy IP Address
    3. HTTP_X_FORWARDED_FOR = Random IP Address
  • security > proxy_level > Elite
  • Elite: Obscures user IP, conceals proxy use.
    1. REMOTE_ADDR = Proxy IP Address
    2. HTTP_VIA = Not Determined
    3. HTTP_X_FORWARDED_FOR = Not Determined
  • security > proxy_level > Transparent
  • Elite: Does not obscure user IP, reveals proxy use (headers: Proxy IP, User IP).
    1. REMOTE_ADDR = Proxy IP Address
    2. HTTP_VIA = Not Determined
    3. HTTP_X_FORWARDED_FOR = End User IP Address
  • security > proxy_type Returns the network or protocol used by the proxy server: http, Tor, web, SOCKS, etc.
    security > proxy_type > HTTP Uses HTTP protocol, accessible to any Internet user.
    security > proxy_type > Service Operated by organizations providing VPN access to subscribers.
    security > proxy_type > SOCKS Uses SOCKS protocol, accessible to any Internet user.
    security > proxy_type > SOCKS HTTP Uses both HTTP and SOCKS protocols, accessible to any Internet user.
    security > proxy_type > Tor Part of the Tor network, routes traffic through changing nodes.
    security > proxy_type > Web Operates via a web browser, proxying user requests through a website.
    security > proxy_type > Privacy Proxy Used by privacy service providers to mask user IPs, with fixed country locations
    security > vpn_service Returns the VPN service name for IPs with anonymizer_status 'private' and proxy_type 'service' (VPN). Not applicable for IPv6.
    security > hosting_facility Indicates if the IP is from a hosting facility (true/false).

    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.

    Requesting JSON Format

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

    Requesting XML Format

    https://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
    

    Example Request:
    Setting the fields object to country_code causes the ipstack API to return only the country_code object.

    https://api.ipstack.com/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.ipstack.com/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": { ... }, }
    <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.0655</latitude> <longitude>-118.2405</longitude> <msa>31100</msa> <dma>803</dma> <radius>null</radius> <ip_routing_type>null</ip_routing_type> <connection_type>null</connection_type> <location> [...] </location> <time_zone> [...] </time_zone> <currency> [...] </currency> <connection> [...] </connection> </result>
    JSONXML

    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.ipstack.com/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 } [...]
    [...] <security> <is_proxy/> <proxy_type/> <is_crawler/> <crawler_name/> <crawler_type/> <is_tor/> <threat_level>high</threat_level> <threat_types>tor</threat_types> <proxy_last_detected/> <proxy_level/> <vpn_service/> <anonymizer_status/> <hosting_facility/> </security> [...]
    JSONXML

    To learn more about each security response object, please refer to the Response Objects section.

    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.ipstack.com/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", [...] }
    <result> <ip>160.39.144.19</ip> <hostname>dyn-160-39-144-19.dyn.columbia.edu</type> [...] </result>
    JSONXML

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

    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.

    Plan Name Monthly Price Number of Calls Overage Price per call Overage Total price
    Basic $12.99 50,000 0.00031176 10,000 $16.11
    Professional $59.99 500,000 0.000143976 10,000 $61.43
    Professional Plus $99.99 2,000,000 0.000059994 10,000 $100.59

    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.

    Introducing Platinum Support - Enterprise-grade support for APILayer

    Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.

    What does Platinum Support include?

    Standard Support Platinum Support
    General review on the issue Tick icon Tick icon
    Access to knowledge base articles Tick icon Tick icon
    Email support communication Tick icon Tick icon
    Regular products updates and fixes Tick icon Tick icon
    Dedicated account team Cross icon Tick icon
    Priority Email Support with unlimited communication Cross icon Tick icon
    Priority bug and review updates Cross icon Tick icon
    Option for quarterly briefing call with product Management Cross icon Tick icon
    Features requests as priority roadmap input into product Cross icon Tick icon

    Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.

    Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.

    Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.

    Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.

    Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.

    Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.

    Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!

    Any questions? We're happy to help!

    Contact Support