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

Getting started overview

Integrating the IPGeolocation API involves a sequence of steps designed to get developers making authenticated requests quickly. This process typically begins with account creation, followed by the generation or retrieval of an API key. This key is essential for authenticating all subsequent API calls. Once the key is secured, developers can proceed to make their initial API request, often using a simple HTTP GET call to a basic endpoint, to verify connectivity and data retrieval. IPGeolocation offers various endpoints beyond basic IP lookup, including Timezone API and User Agent API, all accessible via the same authentication mechanism IPGeolocation documentation. The service provides SDKs in multiple programming languages to streamline integration, supporting JavaScript, PHP, Python, Go, Ruby, and Java.

The core objective of this getting started guide is to enable you to send your first successful request to the IPGeolocation API and receive a valid JSON response. This foundational step confirms that your API key is correctly configured and that you understand the basic request structure. Subsequent steps can then involve exploring more advanced features, integrating SDKs, or handling specific data requirements for your application, such as website personalization or fraud prevention IPGeolocation homepage.

Quick Reference: IPGeolocation Getting Started

Create an account and get keys

To begin using IPGeolocation, you must first create an account. This process typically involves navigating to the IPGeolocation website and choosing a subscription plan. IPGeolocation offers a free tier that permits up to 1,000 requests per day, which is suitable for initial testing and development IPGeolocation pricing details. For higher volumes or additional features like VPN and proxy detection, paid plans are available, starting with the Starter tier.

1. Navigate to the Pricing Page: Visit the IPGeolocation pricing page.
2. Select a Plan: Choose the 'Free' plan or a suitable paid plan based on your anticipated usage. The free plan provides immediate access to the core IP Geolocation API.
3. Complete Registration: Follow the on-screen prompts to register. This usually involves providing an email address and creating a password.
4. Verify Email: An email verification step may be required to activate your account. Check your inbox and spam folder for the verification link.
5. Access Dashboard: Once registered and verified, log in to your IPGeolocation account dashboard.
6. Retrieve API Key: Your unique API key will be displayed prominently within your dashboard. This key is a string of alphanumeric characters that you will use to authenticate all your API requests. Keep this key secure, as it grants access to your account's API usage.

The API key functions as a primary authentication token. When making requests, it is typically passed as a query parameter in the URL. For example, a request might look like https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY. Understanding how API keys facilitate access is fundamental to interacting with most web services, as detailed in general API security practices OAuth 2.0 framework, which often uses tokens for authorization.

Your first request

After obtaining your API key, you can make your first request to the IPGeolocation API. This initial call verifies that your API key is active and that you can successfully receive data. The simplest way to test is by querying your own IP address, or a specified IP address, using the core IP Geolocation API endpoint. The primary endpoint for IP geolocation is https://api.ipgeolocation.io/ipgeo.

Using curl (Command Line)

curl is a widely available command-line tool for making HTTP requests. Replace YOUR_API_KEY with the actual key from your dashboard.

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY'

To target a specific IP address, add the ip parameter:

curl 'https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY&ip=8.8.8.8'

Using JavaScript (Browser or Node.js)

For client-side applications or Node.js environments, you can use the fetch API or a library like axios.

Browser Example:

fetch('https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Node.js Example (using node-fetch or similar):

const fetch = require('node-fetch'); // npm install node-fetch

async function getGeolocation() {
  try {
    const response = await fetch('https://api.ipgeolocation.io/ipgeo?apiKey=YOUR_API_KEY');
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error:', error);
  }
}

getGeolocation();

Using Python

Python's requests library is a common choice for making HTTP requests.

import requests

api_key = 'YOUR_API_KEY'
url = f'https://api.ipgeolocation.io/ipgeo?apiKey={api_key}'

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise an exception for HTTP errors
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

Expected Response

A successful request will return a JSON object containing various details about the IP address, such as country, city, latitude, longitude, and ISP information. The exact structure can be found in the IPGeolocation API reference.

Example (truncated):

{
  "ip": "8.8.8.8",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code2": "US",
  "country_code3": "USA",
  "country_name": "United States",
  "state_prov": "California",
  "city": "Mountain View",
  "zipcode": "94043",
  "latitude": "37.4224",
  "longitude": "-122.0842",
  "isp": "Google LLC",
  "organization": "Google LLC",
  "asn": "AS15169",
  "timezone": {
    "name": "America/Los_Angeles",
    "offset": -7,
    "current_time": "2026-05-29 10:30:00-0700",
    "current_time_unix": 1779999000,
    "is_dst": true,
    "dst_savings": 1
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar"
  },
  "security": {
    "vpn": false,
    "proxy": false,
    "tor": false,
    "threat": "safe"
  }
}

Common next steps

Once you've successfully made your first API call, you can explore IPGeolocation's broader capabilities and integrate them more deeply into your applications. Common next steps include:

1. Explore Additional Endpoints: IPGeolocation offers APIs for specific use cases beyond basic IP lookup, such as the Timezone API, User Agent API, and VPN & Proxy Detection API. Review the documentation to understand their parameters and responses.

2. Integrate with SDKs: For more streamlined development, consider using one of IPGeolocation's official SDKs. They abstract away HTTP request details and provide language-specific methods for interacting with the API. SDKs are available for JavaScript, PHP, Python, Go, Ruby, and Java.

3. Error Handling: Implement robust error handling in your application. API requests can fail due to network issues, invalid API keys, or rate limits. The API typically returns HTTP status codes (e.g., 400 for bad request, 401 for unauthorized, 429 for rate limit) and a JSON error object. Understanding these responses is crucial for creating resilient applications, as emphasized in general API best practices for error management Google Cloud API design guide for errors.

4. Rate Limiting Management: Be aware of your plan's request limits. The free tier allows 1,000 requests per day. For higher volumes, consider upgrading your plan or implementing client-side caching strategies to reduce redundant API calls.

5. Data Parsing and Usage: Parse the JSON response to extract the specific data points your application needs (e.g., country, city, latitude, longitude). Use this data for functionalities like content geo-targeting, website personalization, or basic fraud detection.

6. Security Considerations: Ensure your API key is not exposed in client-side code or public repositories. Store it securely, preferably using environment variables or a secrets management service, especially in server-side applications.

Troubleshooting the first call

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

• Invalid API Key (HTTP 401 Unauthorized): Double-check that you have copied your API key correctly from your IPGeolocation dashboard. Ensure there are no leading or trailing spaces. An incorrect key will result in an authorization error.

• Missing API Key: Verify that the apiKey parameter is included in your request URL. Without it, the API cannot authenticate your request.

• Rate Limit Exceeded (HTTP 429 Too Many Requests): If you are on the free tier, you are limited to 1,000 requests per day. If you've made many rapid requests, you might hit this limit. Wait for the limit to reset or consider upgrading your plan. Check your dashboard for current usage statistics.

• Network Connectivity Issues: Ensure your internet connection is stable. Test connectivity to other websites to rule out local network problems.

• Incorrect Endpoint URL: Confirm that you are using the correct base URL (https://api.ipgeolocation.io/ipgeo) and that there are no typos. Refer to the IPGeolocation API documentation for exact endpoint paths.

• Firewall or Proxy Restrictions: If you are making requests from a corporate network, a firewall or proxy might be blocking outbound HTTP requests to the API endpoint. Consult your network administrator if you suspect this is the case.

• JSON Parsing Errors: If the API returns an error message that isn't immediately clear, ensure your code is correctly parsing the JSON response. Sometimes, an error message might be embedded within a JSON structure that your code expects to be data. Tools like Mozilla Developer Network HTTP status codes reference can help interpret HTTP responses.

• Review Server-Side Logs: If your application is running on a server, check its logs for any error messages related to the API request. These logs can provide more detailed insights into why a request failed.