IP 2 Country Getting Started: First API Call (2026)

Getting started overview

Integrating with IP 2 Country involves a series of steps designed to quickly enable IP-to-country lookups. The process typically begins with account registration, followed by obtaining an API key. This key authenticates your requests to the IP 2 Country API, which primarily uses a RESTful interface for its operations. After securing credentials, developers can construct and execute their first API call to validate the setup and retrieve geolocation data for a specified IP address. IP 2 Country provides a free tier allowing up to 1000 daily queries for testing and light usage, with paid plans available for higher volumes starting at 50,000 daily queries for $29/month, as detailed on their IP 2 Country pricing page.

The API is designed for basic IP-to-country mapping, supporting use cases such as content localization, fraud detection based on country, and geotargeting advertising. Its developer experience is noted for a straightforward REST API with clear documentation on parameters and response formats, eliminating the need for dedicated SDKs and allowing direct HTTP client integration, as outlined in the IP 2 Country developer documentation.

Quick Reference Guide

Create an account and get keys

To begin using the IP 2 Country API, the initial step is to register for an account on their platform. This process typically involves providing an email address and creating a password. Upon successful registration, you will gain access to a personal dashboard where your API key will be available. This API key is a unique identifier that authenticates your requests to the IP 2 Country service, ensuring that API calls are associated with your account and adhere to your subscription limits.

Follow these steps to create your account and retrieve your API key:

1. Navigate to the IP 2 Country Developer Portal: Open your web browser and go to the IP 2 Country developer portal.
2. Sign Up/Register: Look for a "Sign Up" or "Register" button. Click it to initiate the account creation process. You will typically be prompted to enter your email address and create a secure password.
3. Verify Email (if applicable): Some services require email verification. Check your inbox for a confirmation email from IP 2 Country and follow the instructions to verify your account.
4. Access Your Dashboard: Once registered and logged in, you will be directed to your user dashboard.
5. Locate Your API Key: Within the dashboard, there should be a clearly labeled section for "API Key" or "Access Token." Copy this key. It is essential for authenticating all your API requests. Treat your API key like a password to prevent unauthorized usage, as recommended by general API security practices for handling bearer tokens securely.

It is crucial to keep your API key secure and avoid exposing it in client-side code or public repositories. For server-side applications, store the key in environment variables or a secure configuration management system rather than hardcoding it directly into your application's source code.

Your first request

After obtaining your API key, you are ready to make your first request to the IP 2 Country API. The API is a RESTful service, meaning you interact with it using standard HTTP methods, primarily GET requests, to retrieve data. The base endpoint for IP-to-country lookups will require the IP address you wish to query and your API key for authentication.

The general structure for an IP 2 Country API request is as follows:

GET https://api.ip2country.com/v1/{ip_address}?key={your_api_key}

Replace {ip_address} with the IP address you want to look up (e.g., 8.8.8.8 for Google's public DNS) and {your_api_key} with the key you obtained from your dashboard.

Example using cURL

cURL is a command-line tool and library for transferring data with URLs. It is commonly used for making HTTP requests and is available on most operating systems. This example demonstrates how to make a request using cURL:

curl -X GET "https://api.ip2country.com/v1/8.8.8.8?key=YOUR_API_KEY"

Remember to replace YOUR_API_KEY with your actual API key.

Expected JSON Response

A successful request will return a JSON object containing the geolocation information for the queried IP address. The structure of the response typically includes the country code and country name. For example, a lookup for 8.8.8.8 might yield a response similar to this:

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States"
}

This response indicates that the IP address 8.8.8.8 is located in the United States.

Example using Python

For programmatic access, you can use an HTTP client library in your preferred programming language. Here’s an example using Python's requests library:

import requests

api_key = "YOUR_API_KEY"  # Replace with your actual API key
ip_address = "1.1.1.1"  # Example IP address

url = f"https://api.ip2country.com/v1/{ip_address}?key={api_key}"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise an exception for HTTP errors (4xx or 5xx)
    data = response.json()
    print(data)
except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except Exception as err:
    print(f"An error occurred: {err}")

This Python script will print the JSON response to the console, allowing you to parse and utilize the country data within your application.

Common next steps

Once you have successfully made your first API call and confirmed that the IP 2 Country service is working, several common next steps can help you integrate and optimize its use within your applications:

1. Error Handling: Implement robust error handling in your application. The API may return various HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 404 for not found, 429 for too many requests, 500 for internal server error) and error messages. Your application should gracefully handle these scenarios to provide a good user experience and prevent unexpected crashes. Consult the IP 2 Country developer documentation for a full list of error codes.
2. Rate Limiting Management: Be aware of the rate limits associated with your IP 2 Country plan (1000 daily queries for the free tier, more for paid plans). Implement strategies such as client-side caching of frequently requested IP addresses or exponential backoff for retries to avoid exceeding these limits. This is a standard practice for interacting with external APIs, as detailed in guides on managing API rate limits.
3. Asynchronous Requests: For applications requiring high performance or concurrent requests, consider making API calls asynchronously. This prevents your application from blocking while waiting for the IP 2 Country API response, improving responsiveness.
4. Integrate into Application Logic: Begin integrating the country data into your application's core logic. This could involve:
• Content Localization: Displaying content, currency, or language based on the user's country.
• Fraud Prevention: Flagging transactions originating from high-risk countries or detecting discrepancies between billing address country and IP country.
• Analytics: Enriching user analytics data with country-level information for better insights.
• Geotargeting: Customizing advertisements or service availability based on the user's geographic location.
5. Monitor Usage: Regularly check your API usage statistics within your IP 2 Country dashboard. This helps you stay within your plan limits and anticipate when an upgrade might be necessary.
6. Security Best Practices: Reiterate securing your API key. Never embed it directly in client-side code. For server-side applications, use environment variables or a secrets management service. Ensure all communication with the API uses HTTPS.
7. Explore Advanced Features (if applicable): While IP 2 Country focuses on basic IP-to-country, if your needs evolve, review their documentation for any additional parameters or data fields that might be available to enhance your geolocation capabilities.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems you might face when working with the IP 2 Country API:

• Invalid API Key (HTTP 401 Unauthorized):
  • Problem: You receive an HTTP 401 status code or an error message indicating an invalid or missing API key.
  • Solution: Double-check that you have copied your API key correctly from your IP 2 Country dashboard. Ensure there are no leading or trailing spaces. Verify that the key is included in the URL as the key parameter. If you suspect your key has been compromised, consider regenerating it from your dashboard.
• Invalid IP Address (HTTP 400 Bad Request):
  • Problem: The API returns an HTTP 400 status code, often with a message about an invalid IP address format.
  • Solution: Confirm that the IP address you are querying is a valid IPv4 or IPv6 address. Ensure it's not a private IP address (e.g., 192.168.x.x, 10.x.x.x, 172.16.x.x to 172.31.x.x) or a localhost address (127.0.0.1), as these are not routable on the public internet and cannot be geolocated by external services.
• Rate Limit Exceeded (HTTP 429 Too Many Requests):
  • Problem: You receive an HTTP 429 status code, indicating you've sent too many requests in a given period.
  • Solution: If you are on the free tier, you are limited to 1000 daily queries. Wait for the rate limit to reset (typically 24 hours). For higher usage, consider upgrading your plan on the IP 2 Country pricing page or implementing client-side caching and request throttling.
• Network Connectivity Issues:
  • Problem: Your request times out or fails to connect, without a specific API error code.
  • Solution: Check your internet connection. Ensure there are no firewall rules or proxy settings on your network that are blocking outbound connections to api.ip2country.com. Try making a request to another well-known public API (e.g., https://api.github.com) to rule out general network problems, as discussed in MDN Web Docs on HTTP status codes.
• Incorrect Endpoint URL:
  • Problem: You receive an HTTP 404 Not Found error.
  • Solution: Verify that the base URL and path segment (/v1/{ip_address}) are exactly as specified in the IP 2 Country API documentation. A common mistake is a typo in the domain or path.
• Unexpected Response Format:
  • Problem: The API returns data, but it's not in the expected JSON format, or specific fields are missing.
  • Solution: Review the IP 2 Country API reference to confirm the expected response structure. Ensure your HTTP client is correctly interpreting the response as JSON.

If you continue to experience issues after trying these steps, consult the official IP 2 Country documentation or contact their support team for further assistance.