IPInfoDB Getting Started: Account, Keys, First Request (2026)

Getting started overview

To begin using the IPInfoDB API, developers generally follow a three-step process: account creation, API key retrieval, and making an initial API call. IPInfoDB's service allows for the lookup of geographic information associated with both IPv4 and IPv6 addresses. The API supports various response formats, including XML, JSON, and CSV, which can be specified in the request parameters. Authentication for all API calls relies on a unique API key, which must be included as a query parameter in each request.

The service offers a free tier for basic usage, providing up to 15,000 lookups per day with a rate limit of 2 lookups per second. For higher volumes or more advanced features, various paid plans are available, starting with the Pro Plan at $20 per month. This guide focuses on the initial steps to configure and execute your first successful API request.

Quick Start Reference

The following table summarizes the essential steps for getting started with IPInfoDB:

Create an account and get keys

Before making API requests, you need to create an IPInfoDB account to obtain your unique API key. The API key serves as the primary method for authenticating your requests to the IPInfoDB service.

Account Registration

1. Navigate to the IPInfoDB website.
2. Click on the "Sign Up" or "Register" option, typically found on the pricing or login pages.
3. Complete the registration form by providing the required information, such as your email address and a password.
4. Verify your email address if prompted, which is a common step for new account activations.

API Key Retrieval

Once your account is active:

1. Log in to your newly created IPInfoDB account.
2. Access your personal dashboard or account settings. The API key is usually displayed prominently in a section labeled "API Key" or "Your Key."
3. Copy this key. It is a string of alphanumeric characters that you will include in every API request. Keep this key secure, as it identifies your account and usage.

Your first request

With an active account and your API key, you can now make your first IP geolocation request. IPInfoDB provides several API endpoints for different types of lookups. The most common is the city-level geolocation API.

API Endpoints

IPInfoDB offers two main API endpoints for geolocation lookups:

• City-level Geolocation: Provides detailed information including country name, region, city, and coordinates.
• Country-level Geolocation: Returns only country code and country name.

For this guide, we will use the city-level API endpoint: https://api.ipinfodb.com/v3/ip-city/. The official API documentation provides a comprehensive overview of all available endpoints and parameters.

Request Parameters

Each request requires specific parameters:

• key: Your unique API key (required).
• ip: The IP address you want to look up (required).
• format: The desired response format (xml, json, or csv). Defaults to xml if not specified.

Example Request using cURL

To make a request, replace YOUR_API_KEY with your actual key and TARGET_IP_ADDRESS with the IP address you wish to look up (e.g., 8.8.8.8 for Google's public DNS server).

curl "https://api.ipinfodb.com/v3/ip-city/?key=YOUR_API_KEY&ip=TARGET_IP_ADDRESS&format=json"

Example Response (JSON)

A successful request for 8.8.8.8 with format=json might yield a response similar to this, though specific values may vary:

{
  "statusCode": "OK",
  "statusMessage": "",
  "ipAddress": "8.8.8.8",
  "countryCode": "US",
  "countryName": "United States",
  "regionName": "California",
  "cityName": "Mountain View",
  "zipCode": "94043",
  "latitude": "37.38605",
  "longitude": "-122.08385",
  "timeZone": "-07:00"
}

Example Request using JavaScript (Fetch API)

You can also integrate this into a web application using the Fetch API. Note that making direct API calls from client-side JavaScript to external APIs can expose your API key. For production applications, server-side requests are generally recommended to keep your API key secure.

const apiKey = 'YOUR_API_KEY';
const targetIp = '8.8.8.8';
const format = 'json';

fetch(`https://api.ipinfodb.com/v3/ip-city/?key=${apiKey}&ip=${targetIp}&format=${format}`)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error fetching IP geolocation:', error);
  });

For more secure handling of sensitive credentials like API keys in client-side applications, techniques like using a proxy server or environment variables during development are commonly employed, as discussed in Google Cloud's API key security guidelines.

Common next steps

After successfully making your first API call, you might consider these common next steps:

• Error Handling: Implement robust error handling in your application to manage cases where the API returns an error status (e.g., invalid key, rate limit exceeded, invalid IP format). The statusCode and statusMessage fields in the JSON response are crucial for this.
• Rate Limiting: Be aware of the API rate limits (e.g., 2 lookups per second for the free tier) and implement strategies like exponential backoff or token buckets to avoid exceeding limits and incurring temporary blocks.
• Data Parsing and Usage: Integrate the parsed geolocation data into your application logic. This could involve displaying location on a map, customizing content based on region, or enhancing security features.
• Security Best Practices: If you are deploying your application, ensure your API key is not exposed client-side or committed directly into version control. Use environment variables or a secure configuration management system. Consider server-side API calls to protect your key.
• Explore Other Endpoints: Review the IPInfoDB API documentation to understand other available endpoints, such as the country-level lookup, and their specific parameters.
• Upgrade Plan: If your usage exceeds the free tier limits, consider upgrading to a paid plan to accommodate higher request volumes and access potentially enhanced features.
• Database Download: For very high-volume or offline requirements, IPInfoDB also offers a downloadable IP Geolocation Database, which might be a more suitable solution than repeated API calls.

Troubleshooting the first call

If your initial API call does not return the expected data, consider the following troubleshooting steps:

1. Check API Key: Double-check that your API key is correct and has been copied exactly from your IPInfoDB dashboard. An incorrect key will result in an authentication error.
2. Verify IP Address Format: Ensure the ip parameter contains a valid IPv4 or IPv6 address. Invalid formats may lead to an error response.
3. Review Endpoint URL: Confirm that the base URL for the API endpoint (e.g., https://api.ipinfodb.com/v3/ip-city/) is correct and free of typos.
4. HTTP Status Codes: While IPInfoDB typically reports errors in the JSON/XML response, also observe the HTTP status code returned. A 403 Forbidden or 401 Unauthorized often indicates an API key issue. A 400 Bad Request might point to malformed parameters.
5. Examine Response Body: Carefully read the statusMessage field in the API response. This field provides specific details about why a request failed (e.g., "Invalid API Key," "Daily lookup limit exceeded").
6. Rate Limit Exceeded: If you make too many requests in a short period, you might hit the rate limit. Wait a few seconds or minutes and try again. The free tier limits are 2 lookups per second and 15,000 lookups per day.
7. Internet Connectivity: Ensure your development environment has an active internet connection and can reach the IPInfoDB API server.
8. Firewall/Proxy Settings: If you are on a corporate network, a firewall or proxy might be blocking outbound API calls. Consult your network administrator if this is suspected.
9. Consult Documentation: Refer to the IPInfoDB API documentation for detailed error codes and explanations.