ip-api Getting Started: Quickstart Guide (2026)

Getting started overview

Getting started with ip-api involves a sequence of steps to configure access and make your initial API call. The process typically includes creating an account, understanding the available API endpoints, and constructing a request to retrieve IP geolocation data. ip-api offers both a free tier for non-commercial use with specific rate limits and paid plans that provide increased request volumes and HTTPS support for commercial applications.

The API is designed to be straightforward, returning data in formats such as JSON, XML, or CSV. This guide focuses on the essential steps to get a working implementation, from account setup to a successful first request.

Here's a quick reference table outlining the getting started process:

Create an account and get keys

To begin using ip-api, navigate to the ip-api pricing page. While a formal 'API key' isn't explicitly required for the free, non-commercial HTTP tier, creating an account helps manage your usage and provides access to account-specific features. For commercial use, or to access HTTPS and higher rate limits, you will need to subscribe to a paid plan, such as the Developer Plan starting at $15/month.

Upon subscribing to a paid plan, your API key will be provided within your account dashboard. This key is essential for authenticating your requests when using the commercial endpoints and for accessing HTTPS. The ip-api documentation on authentication provides further details on how to integrate your API key into your requests.

For the free tier, access is generally based on your originating IP address. This means that while you don't use a specific key in your request URL, your usage is still tracked and subject to the 150 requests per minute rate limit. It's important to understand this distinction as you plan your integration, particularly if you anticipate scaling beyond non-commercial, HTTP-only use.

Your first request

After understanding the account and key requirements, you can make your first request to the ip-api. The API supports various output formats including JSON, XML, and CSV. For most modern applications, JSON is the preferred format due to its widespread compatibility and ease of parsing.

The basic endpoint for IP geolocation is http://ip-api.com/json/. To look up your own public IP address, you can simply make a GET request to this endpoint. To look up a specific IP address, append it to the URL, for example: http://ip-api.com/json/8.8.8.8.

Example using curl (for your own IP):

curl http://ip-api.com/json/

Example using curl (for a specific IP):

curl http://ip-api.com/json/8.8.8.8

Expected JSON Response Structure:

A successful request will return a JSON object containing various geolocation details. The structure will resemble the following (values will vary based on the IP queried):

{
  "status": "success",
  "country": "United States",
  "countryCode": "US",
  "region": "CA",
  "regionName": "California",
  "city": "Mountain View",
  "zip": "94043",
  "lat": 37.422,
  "lon": -122.084,
  "timezone": "America/Los_Angeles",
  "isp": "Google LLC",
  "org": "Google",
  "as": "AS15169 Google LLC",
  "query": "8.8.8.8"
}

For paid plans requiring an API key, the request URL structure changes slightly to include your key. Consult the ip-api API key usage documentation for specific examples on how to include your key securely.

Common next steps

After successfully making your first request, consider these common next steps to integrate ip-api into your application:

1. Parse the Response: Implement logic in your application to parse the JSON (or XML/CSV) response. Access specific fields like country, city, or lat/lon as needed for your application's functionality. Many programming languages have built-in JSON parsers or readily available libraries. For example, in JavaScript, you'd use JSON.parse(); in Python, json.loads().
2. Error Handling: Implement robust error handling. The API returns a status field in its JSON response that can be success or fail. If fail, an additional message field provides details. For example, a common error is exceeding rate limits.
3. Rate Limit Management: Understand and respect the API's rate limits. The free tier is limited to 150 requests per minute. For commercial applications or higher volumes, upgrade to a paid plan. Implement client-side rate limiting or caching strategies to avoid hitting limits unnecessarily. The ip-api documentation on rate limits provides detailed information.
4. HTTPS for Production: If you are using ip-api in a production environment, especially for commercial purposes, always use HTTPS. The free tier only supports HTTP. Paid plans enable HTTPS, which encrypts data in transit, protecting sensitive information and ensuring data integrity. This is a standard security practice for web APIs, as described in the Mozilla Developer Network's HTTPS explanation.
5. Proxy/VPN Detection: Explore additional features like proxy/VPN detection if your application requires identifying users behind such services. This is available as part of ip-api's core offerings. Refer to the ip-api proxy detection documentation for implementation details.
6. Batch Requests: For efficiency, if you need to look up multiple IP addresses, investigate if ip-api offers a batch request endpoint. This can reduce the number of individual API calls and improve performance. Check the ip-api documentation for batch requests.
7. Integrate with Mapping Services: Once you have latitude and longitude coordinates, you can integrate with mapping services like Google Maps Platform or ArcGIS to visualize the IP's location. For example, the Google Maps JavaScript API overview provides a starting point for displaying maps.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check Network Connectivity: Ensure your machine has an active internet connection and can reach ip-api.com.
• Verify URL: Double-check the API endpoint URL for typos. Ensure it's http://ip-api.com/json/ for the free tier, or the correct HTTPS endpoint with your key for paid plans.
• Rate Limit Exceeded: If you receive a status of fail with a message indicating rate limits, wait a minute and try again. For continuous high-volume usage, consider upgrading your plan. The ip-api rate limit policy details the limits.
• Incorrect IP Address Format: If you're querying a specific IP, ensure it's a valid IPv4 or IPv6 address.
• Firewall/Proxy Issues: Your local network's firewall or proxy server might be blocking outbound requests to ip-api.com. Check your network configuration or try making the request from a different network environment.
• DNS Resolution: Ensure your system can correctly resolve ip-api.com to its IP address. You can test this using tools like ping ip-api.com or nslookup ip-api.com.
• API Key Missing/Invalid (Paid Plans): If you are on a paid plan, verify that your API key is correctly included in the request URL as specified in the ip-api API key usage documentation. An invalid or missing key will result in an authentication failure.
• HTTP vs. HTTPS Mismatch: Remember that the free tier only supports HTTP. Attempting to use HTTPS with the free tier will likely result in a connection error. Paid plans require HTTPS.
• Consult Documentation: The official ip-api documentation is the most authoritative source for troubleshooting specific error codes and messages.