API Key & Authentication

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 the IPstack API by simply adding your access_API_key in the base URL as a query parameter. For example,

Base URL:

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

Sign Up to Run API Request

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

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

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

Available Endpoints

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

• Standard Lookup: Look up the data behind an IP address.

• Bulk Lookup: Look up the data behind multiple IP addresses at once.

• Requester Lookup: Look up the data behind the IP address your API request is coming from.

Connecting via HTTPS

All 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, 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

Error Codes

If something goes wrong and the resource you requested is not available or an API call fails, the IPstack API will return 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.

Example Response: Your API response will be wrapped inside your preferred callback function.

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

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 exist