3-Step Quickstart Guide

Jump right into it and learn how to make API requests in seconds using our 3-Step Quickstart Guide.

Code Examples

Skip to code examples in various programming languages, such as JavaScript (jQuery.ajax) and PHP (cURL).

Code Examples

API Documentation

ipapi provides an easy-to-use API interface allowing customers to look various pieces of information IPv4 and IPv6 addresses are associated with. For each IP address processed, the API returns more than 45 unique data points, such as location data, connection data, ISP information, time zone, currency and security assessment data.

The API is REST-based, lookup requests are made using straightforward HTTP GET URLs and results are returned in lightweight JSON or XML format within a matter of a few milliseconds.

This API documentation will outline in detail the API's specification, access and features. At the very bottom you will find code examples in different programming languages. In case any technical questions are left unanswered, please feel free to contact ipapi Customer Service.

Specs & Overview

API Access Key & Authentication

After creating an account, you will be assigned a API access key, a unique hash consisting of 32 characters that will allow you to authenticate with the ipapi API interface. To do this, simply append your API access key to the API's base URL using the access_key parameter. 

https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY

Keep your API access key safe: Your API access key is private and should at no time be shown publicly. You can reset it with immediate effect using your account dashboard at any given time.

API Response

Following a successful API request, the API will return more than 40 unique response objects containing result data. An API response can be returned in JSON or XML format and is structured into 4 modules: General information, location data, time zone data, currency data, connection data and security data. Response objects contained in each module will be explained in detail in the API Response Objects section.

Find below an example API response for an IPv4 address in Brooklyn, New York.

Example API Response: 

{
    "ip": "161.185.160.93",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "NY",
    "region_name": "New York",
    "city": "Bath Beach",
    "zip": "11201",
    "latitude": 40.69459915161133,
    "longitude": -73.99063873291016,
    "msa": "35620",
    "dma": "501",
    "radius": 30.012950897216797,
    "ip_routing_type": "fixed",
    "connection_type": "tx",
    "location": {
        "geoname_id": 5108111,
        "capital": "Washington D.C.",
        "languages": [
            {
                "code": "en",
                "name": "English",
                "native": "English"
            }
        ],
        "country_flag": "http://assets.ipapi.com/flags/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-09-24T05:07:10-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": 22252,
        "isp": "The City of New York",
        "sld": "nyc",
        "tld": "gov",
        "carrier": "the city of new york",
        "home": false,
        "organization_type": "Government (Municipal)",
        "isic_code": "O8411",
        "naics_code": "009211"
    },
    "security": {
        "is_proxy": null,
        "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>161.185.160.93</ip>
    <hostname>161.185.160.93</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>NY</region_code>
    <region_name>New York</region_name>
    <city>Brooklyn</city>
    <zip>11238</zip>
    <latitude>40.676</latitude>
    <longitude>-73.9629</longitude>
    <msa>35620</msa>
    <dma>501</dma>
    <radius>30.01295</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>tx</connection_type>
    <location>
        <geoname_id>5110302</geoname_id>
        <capital>Washington D.C.</capital>
        <languages>
            <code>en</code>
            <name>English</name>
            <native>English</native>
        </languages>
        <country_flag>https://assets.ipapi.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-09-24T08:27:07-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>22252</asn>
          <isp>The City of New York</isp>
          <sld>nyc</sld>
          <tld>gov</tld>
          <carrier>the city of new york</carrier>
          <home>false</home>
          <organization_type>Government (Municipal)</organization_type>
          <isic_code>O8411</isic_code>
          <naics_code>009211</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

Please note: To be able to show you a comprehensive API response, Hostname and Security data have been included in the result above. To enable this data for your API response, please follow the instructions in the following sections of this documentation: Hostname Lookup and Security Data.

API Endpoints

The API comes with a total of 3 available API endpoints, each covering a different type functionality. Please find below a quick overview and click on any of the endpoints to learn more about its usage.

256-bit HTTPS Encryption Available on: Standard Plan and higher

If supported by your subscription, you can connect to the API using industry standard HTTPS (SSL) by appending an s to the HTTP Protocol. You can see an example API request using HTTPS below.

Example API Request: 

https://api.ipapi.com/api/161.185.160.93

JSONP Callbacks

The API supports JSONP Callbacks. To make use of this feature, simply append the API's callback parameter to your API request URL and set it to your preferred function name. The API will then return your API results set wrapped inside the tags of the function you specified.

Example API Request: 

https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY
    & callback = FUNCTION_NAME

Example API Response: 

CALLBACK_FUNCTION ({
    {
        "ip": "161.185.160.93",
        "hostname": "161.185.160.93",
        "type": "ipv4",
        "continent_code": "NA",
        "continent_name": "North America",
        "country_code": "US",
        "country_name": "United States",
        "region_code": "NY",
        [...]
    }
})JSON ONLY

Please note: The API also supports Access-Control (CORS) headers.

API Error Codes

In the event that your API request fails for any reason, the API will return a JSON error message detailing information about the error that occurred. As an example, find below an error the API responds with if the limit of monthly API requests has been reached.

Example Error: 

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

Common API Errors:

Code Type Info
404 404_not_found User requested a resource which does not exist.
101 missing_access_key User did not supply an access key.
101 invalid_access_key User supplied an invalid access key.
102 inactive_user User account is inactive or blocked.
103 invalid_api_function User requested a non-existent API function.
104 usage_limit_reached User has reached his subscription's monthly request allowance.
105 function_access_restricted The user's current subscription does not support this API function.
301 invalid_fields User specified one or more invalid fields inside the fields parameter.
302 too_many_ips User specified too many IP addresses in a single Bulk Lookup request.
303 batch_not_supported_on_plan The user's current subscription plan does not support Bulk Lookup.

Endpoints

Standard IP Lookup Available on: All plans

To look up a single IP address of your choice, simply append an IPv4 or IPv6 address to the API's base URL. Below you will find an example API request, required parameters and an example API response.

Example API Request:

https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Object Description
IP Address [Required] An IPv4 or IPv6 address of your choice. It is also possible to enter a domain URL to have the API resolve the domain to the underlying IP address.
access_key [Required] Your API access key, available in your account dashboard.
fields [optional] Specify API response field(s) according to the Specify Response Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable Security Data.
language [optional] Set to a 2-letter language code according to the Specify Response Language section to specify response 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.

Example API Response:

A standard API response will come with general information about the given IP address and location data. If you are subscribed to the Standard Plan or higher, the API will additionally return time zone, currency and connection data.

{
    "ip": "161.185.160.93",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "NY",
    "region_name": "New York",
    "city": "Bath Beach",
    "zip": "11201",
    "latitude": 40.69459915161133,
    "longitude": -73.99063873291016,
    "msa": "35620",
    "dma": "501",
    "radius": 30.012950897216797,
    "ip_routing_type": "fixed",
    "connection_type": "tx",
    "location": {
        "geoname_id": 5110302,
        "capital": "Washington D.C.",
        "languages": [
            {
                "code": "en",
                "name": "English",
                "native": "English"
            }
        ],
        "country_flag": "http://assets.ipapi.com/flags/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-14T00:26:20-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": 22252,
        "isp": "The City of New York",
        "sld": "nyc",
        "tld": "gov",
        "carrier": "the city of new york",
        "home": false,
        "organization_type": "Government (Municipal)",
        "isic_code": "O8411",
        "naics_code": "009211"
    }
}
<result>
    <ip>161.185.160.93</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>Bath Beach</city>
    <zip>11201</zip>
    <latitude>40.6945</latitude>
    <longitude>-73.9906</longitude>
    <msa>35620</msa>
    <dma>501</dma>
    <radius>30.01295</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>tx</connection_type>
    <location>
        <geoname_id>5110302</geoname_id>
        <capital>Washington D.C.</capital>
        <languages>
            <code>en</code>
            <name>English</name>
            <native>English</native>
        </languages>
        <country_flag>https://assets.ipapi.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-09-24T08:27:07-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>22252</asn>
          <isp>The City of New York</isp>
          <sld>nyc</sld>
          <tld>gov</tld>
          <carrier>the city of new york</carrier>
          <home>false</home>
          <organization_type>Government (Municipal)</organization_type>
          <isic_code>O8411</isic_code>
          <naics_code>009211</naics_code>
      </connection>
</result>
JSONXML

API Response Objects: Looking for details about the response objects returned by the API? All available response objects are explained in detail in the API Response Objects section.

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 Available on: Business Plan and higher

To look up multiple IP addresses at once, simply attach a comma-separated list of IPv4 or IPv6 addresses to the API's base URL. The API will then respond with an array of results, containing one sub-array per IP address looked up.

Example API Request:

https://api.ipapi.com/api/161.185.160.93,87.111.168.248,210.138.184.59
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Object Description
IP Addresses [Required] A comma-separated list of IPv4 or IPv6 addresses of your choice. It is also possible to enter domain URLs to have the API resolve the underlying IP addresses. (Limit: 50 values)
access_key [Required] Your API access key, available in your account dashboard.
fields [optional] Specify API response field(s) according to the Specify Response Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable Security Data.
language [optional] Set to a 2-letter language code according to the Specify Response Language section to specify response 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.

Example API Response:

A Bulk Lookup API response contains an array of results with each result associated with one of the IP addresses contained in the API request. The API results below have been shortened for readability purposes.

{
    "ip": "161.185.160.93",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "NY",
    "region_name": "New York",
    "city": "Bath Beach",
    "zip": "11201",
    "latitude": 40.676,
    "longitude": -73.9629,
    "msa": "35620",
    "dma": "501",
    "radius": 30.012950897216797,
    "ip_routing_type": "fixed",
    "connection_type": "tx",
    [...]
},
{
    "ip": "87.111.168.248",
    "type": "ipv4",
    "continent_code": "EU",
    "continent_name": "Europe",
    "country_code": "ES",
    "country_name": "Spain",
    "region_code": "GA",
    "region_name": "Madrid",
    "city": "Madrid",
    "zip": "28013",
    "latitude": 40.4189,
    "longitude": -3.7117,
    "msa": null,
    "dma": null,
    "radius": null,
    "ip_routing_type": "fixed",
    "connection_type": "fixed wireless",
    [...]
},
{
    "ip": "210.138.184.59",
    "type": "ipv4",
    "continent_code": "AS",
    "continent_name": "Asia",
    "country_code": "JP",
    "country_name": "Japan",
    "region_code": "13",
    "region_name": "Tokyo",
    "city": "Tokyo",
    "zip": "101-0047",
    "latitude": 35.6907,
    "longitude": 139.7691,
    "msa": null,
    "dma": null,
    "radius": null,
    "ip_routing_type": "fixed",
    "connection_type": "dsl",
    [...]
}
<result>
    <ip>161.185.160.93</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>Bath Beach</city>
    <zip>11201</zip>
    <latitude>40.6945</latitude>
    <longitude>-73.9906</longitude>
    <msa>35620</msa>
    <dma>501</dma>
    <radius>30.01295</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>tx</connection_type>
    [...]
</result>
<result>
    <ip>87.111.168.248</ip>
    <type>ipv4</type>
    <continent_code>EU</continent_code>
    <continent_name>Europe</continent_name>
    <country_code>ES</country_code>
    <country_name>Spain</country_name>
    <region_code>GA</region_code>
    <region_name>Madrid</region_name>
    <city>Madrid</city>
    <zip>28013</zip>
    <latitude>40.4189</latitude>
    <longitude>-3.7117</longitude>
    <msa>null</msa>
    <dma>null</dma>
    <radius>null</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>fixed wireless</connection_type>
    [...]
</result>
<result>
    <ip>210.138.184.59</ip>
    <type>ipv4</type>
    <continent_code>AS</continent_code>
    <continent_name>Asia</continent_name>
    <country_code>JP</country_code>
    <country_name>Japan</country_name>
    <region_code>13</region_code>
    <region_name>Tokyo</region_name>
    <city>Tokyo</city>
    <zip>101-0047</zip>
    <latitude>35.6907</latitude>
    <longitude>139.7691</longitude>
    <msa>null</msa>
    <dma>null</dma>
    <radius>null</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>dsl</connection_type>
    [...]
</result>
JSONXML

API Response Objects: Looking for details about the response objects returned by the API? All available response objects are explained in detail in the API Response Objects section.

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.

Origin IP Lookup Available on: All plans

To look up the IP address the current API request is coming from, simply attach check to the API's base URL. The API will then perform a lookup request based on that IP address and return a full set of API results.

Example API Request:

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

Request Parameters:

Object Description
access_key [Required] Your API access key, available in your account dashboard.
fields [optional] Specify API response field(s) according to the Specify Response Fields section.
hostname [optional] Set to 1 to enable Hostname Lookup.
security [optional] Set to 1 to enable Security Data.
language [optional] Set to a 2-letter language code according to the Specify Response Language section to specify response 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.

Example API Response:

{
    "ip": "161.185.160.93",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code": "US",
    "country_name": "United States",
    "region_code": "NY",
    "region_name": "New York",
    "city": "Bath Beach",
    "zip": "11201",
    "latitude": 40.676,
    "longitude": -73.9629,
    "msa": "35620",
    "dma": "501",
    "radius": 30.012950897216797,
    "ip_routing_type": "fixed",
    "connection_type": "tx",
    "location": {
        "geoname_id": 5108111,
        "capital": "Washington D.C.",
        "languages": [
            {
                "code": "en",
                "name": "English",
                "native": "English"
            }
        ],
        "country_flag": "http://assets.ipapi.com/flags/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-14T00:35:46-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": 22252,
        "isp": "The City of New York",
        "sld": "nyc",
        "tld": "gov",
        "carrier": "the city of new york",
        "home": false,
        "organization_type": "Government (Municipal)",
        "isic_code": "O8411",
        "naics_code": "009211"
    }
}
<result>
    <ip>161.185.160.93</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>Bath Beach</city>
    <zip>11201</zip>
    <latitude>40.6945</latitude>
    <longitude>-73.9906</longitude>
    <msa>35620</msa>
    <dma>501</dma>
    <radius>30.01295</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>tx</connection_type>
    <location>
        <geoname_id>5110302</geoname_id>
        <capital>Washington D.C.</capital>
        <languages>
            <code>en</code>
            <name>English</name>
            <native>English</native>
        </languages>
        <country_flag>https://assets.ipapi.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-09-24T08:27:07-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>22252</asn>
          <isp>The City of New York</isp>
          <sld>nyc</sld>
          <tld>gov</tld>
          <carrier>the city of new york</carrier>
          <home>false</home>
          <organization_type>Government (Municipal)</organization_type>
          <isic_code>O8411</isic_code>
          <naics_code>009211</naics_code>
      </connection>
</result>
JSONXML

API Response Objects: Looking for details about the response objects returned by the API? All available response objects are explained in detail in the API Response Objects section.


Basic Request:

Response Objects

Based on which plan you are subscribed to and the options you specify for your API request, there are over 40 unique response objects the API is capable of responding with. Find below a complete list of API response objects:

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 > 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 Response Format Available on: All plans

    The API is capable of delivering API results in JSON (default) and XML format. The response format can be controlled by appending the API's output parameter to your API request URL and setting it to json or xml.

    Example API Request - JSON:

    https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY    & output = json

    Example API Request - XML:

    https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY
    & output = xml

    Would you like to see an API response? Jump to the API Response section.

    Specify Response Fields Available on: All plans

    API responses from ipapi can be extensive in size. To limit your API result set to specific fields or types of information, simply append the API's fields parameter to your API request URL and set it to a specific field or a comma-separated list of fields.

    Examples:

    fields = main // returns general API fields, only from "ip" to "longitude"
  
fields = city // returns only the "city" object

fields = location // returns the complete "location" object with sub-objects
fields = location.calling_code // returns only the "calling_code" object inside "location"
  
fields = latitude,longitude // returns both the "latitude" and the "longitude" objects

    Example API Request - JSON:

    https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY
    & fields = latitude,longitude

    Would you like to see an API response? Jump to the API Response section.

    Specify Response Language Available on: All plans

    The API is capable of translating certain applicable objects contained in the API response. The default language is always English; other languages can be requested by appending the API's language to your API request URL and setting it to one of the available 2-letter language codes.

    Available Language Codes:

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

    Example API Request:

    In the example request below we are specifying Spanish as language.

    https://api.ipapi.com/api/161.185.160.93
    ? access_key = YOUR_ACCESS_KEY
    & language = es

    Example API Response:

    In the example response below you will notice that all applicable response objects have been translated to Spanish. Please note that the API response has been shortened for readability purposes.

    {
    "ip": "161.185.160.93",
    "type": "ipv4",
    "continent_code": "NA",
    "continent_name": "Norteamérica",  <-- translated
    "country_code": "US",
    "country_name": "Estados Unidos",  <-- translated
    "region_code": "NY",
    "region_name": "Nueva York",  <-- translated
    "city": "Bath Beach",
    "zip": "11201",
    "latitude": 40.6945,
    "longitude": -73.9960,
    "msa": "35620",
    "dma": "501",
    "radius": 30.012950897216797,
    "ip_routing_type": "fixed",
    "connection_type": "tx"
    [...]
}
    <result>
    <ip>161.185.160.93</ip>
    <type>ipv4</type>
    <continent_code>NA</continent_code>
    <continent_name>Norteamérica</continent_name>  <-- translated
    <country_code>US</country_code>
    <country_name>Estados Unidos</country_name>  <-- translated
    <region_code>NY</region_code>
    <region_name>Nueva York</region_name>  <-- translated
    <city>Bath Beach</city>
    <zip>11201</zip>
    <latitude>40.6945</latitude>
    <longitude>-73.9906</longitude>
    <msa>35620</msa>
    <dma>501</dma>
    <radius>30.01295</radius>
    <ip_routing_type>fixed</ip_routing_type>
    <connection_type>tx</connection_type>
    [...]
</result>
    JSONXML

    Enable Hostname Lookup Available on: All plans

    To reduce bandwidth and speed up API responses standard IP lookups do not return hostname information. To include hostname data in your API responses, simply append the API's hostname parameter and set it to 1.

    Example API Request:

    https://api.ipapi.com/api/1.4.193.15
    ? access_key = YOUR_ACCESS_KEY
    & hostname = 1

    Example API Response:

    As you can see below, hostname information is now returned right after the IP address.

    {
    "ip": "1.4.193.15",
    "hostname": "node-cun.pool-1-4.dynamic.totbb.net",
    [...]
}
    <result>
    <ip>161.185.160.93</ip>
    <hostname>node-cun.pool-1-4.dynamic.totbb.net</type>
    [...]
</result>
    JSONXML

    Please note: Enabling Hostname Lookup may cause the speed of API requests to decrease slightly.

    Enable Security Data Available on: Business Pro Plan and higher

    The API is capable of delivering valuable security assessment data, including the detection of threats like the TOR Network, proxies, and more. To enable Security Data in your API request, simply append the API's security parameter to your API request URL and set it to 1.

    Example API Request:

    https://api.ipapi.com/api/76.8.255.114
    ? access_key = YOUR_ACCESS_KEY
    & security = 1

    Example API Response:

    In the API response below you will notice that the threat types attack_source and attack_source_mail have been detected, indicating that the given IP address is in some way associated with spam via email.

    {
    [...]
    "security": {
        "is_proxy": false,
        "proxy_type": null,
        "is_crawler": false,
        "crawler_name": null,
        "crawler_type": null,
        "is_tor": false,
        "threat_level": "high",
        "threat_types": [
            "attack_source",
            "attack_source_mail"
        ],
        "proxy_last_detected": null,
        "proxy_level": null,
        "vpn_service": null,
        "anonymizer_status": null,
        "hosting_facility": false
    }
}
    <result>
      [...]
      <security>
          <is_proxy/>
          <proxy_type/>
          <is_crawler/>
          <crawler_name/>
          <crawler_type/>
          <is_tor/>
          <threat_level>high</threat_level>
          <threat_types>attack_source</threat_types>
          <threat_types>attack_source_mail</threat_types>
          <proxy_last_detected/>
          <proxy_level/>
          <vpn_service/>
          <anonymizer_status/>
          <hosting_facility/>
      </security>
</result>
    JSONXML

    Please note: In the above response the rest of the API response has been skipped for readability purposes.

    Code Examples

    PHP (CURL)

    Standard Lookup via PHP

    Find below a PHP (CURL) example making use of the Standard Lookup endpoint:

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

// Initialize CURL:
$ch = curl_init('https://api.ipapi.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 "calling_code" object inside "location"
echo $api_result['location']['calling_code'];

    JavaScript (jQuery.ajax)

    Standard Lookup via JavaScript (jQuery.ajax)

    Find below a JS example making use of the Standard Lookup endpoint:

    // 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.ipapi.com/' + ip + '?access_key=' + access_key,   
    dataType: 'jsonp',
    success: function(json) {

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

    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
    Standard $12.99 50,000 0.0003897 10,000 $16.89
    Business $59.99 500,000 0.00017997 10,000 $61.79
    Business Pro $99.99 2,000,000 0.0000749925 10,000 $100.74

    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
    Access to knowledge base articles
    Email support communication
    Regular products updates and fixes
    Dedicated account team
    Priority Email Support with unlimited communication
    Priority bug and review updates
    Option for quarterly briefing call with product Management
    Features requests as priority roadmap input into product

    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!

    Upgrade now

    Any technical questions left? Reach out to us, our team is happy to help. Contact Us