IPGEO Getting Started: Account, Keys, and First Request (2026)

Getting started overview

Integrating with the IPGEO API involves a sequence of steps designed to get developers operational quickly. The process begins with account registration, which provisions the necessary API credentials. Following registration, developers will retrieve their API key from the dashboard. This key is then included in HTTP requests to the IPGEO endpoint to authenticate and authorize API calls. A core feature of IPGEO is its free tier, which supports up to 1,000 requests per day, allowing for initial development and testing without immediate cost. The API is structured to provide basic IP geolocation data, including country, city, and coordinates, which are useful for applications requiring content localization, fraud detection, or simple analytics based on user location.

IPGEO supports common development patterns and provides code examples in cURL, Python, PHP, and JavaScript to facilitate initial integration. The API endpoint is designed for direct HTTP GET requests, making it accessible from various programming environments. Developers can expect responses in JSON format, which is a standard data interchange format for web APIs, making it straightforward to parse and integrate into applications as defined by the JSON standard. This Getting Started guide focuses on the critical steps to make your first successful API call and interpret the results.

Create an account and get keys

To begin using IPGEO, the first step is to create an account. This process establishes your user profile and automatically generates the API key required for authentication. The API key serves as your unique identifier and authorization token for all requests made to the IPGEO API.

Registration

1. Navigate to the IPGEO website: Visit the official IPGEO homepage.
2. Sign up: Locate the 'Sign Up' or 'Get Started Free' button, typically prominent on the homepage.
3. Provide credentials: Enter your email address and create a secure password. Agree to the terms of service.
4. Account activation: After submitting your details, you may receive an email to verify your account. Follow the instructions in the email to complete the activation process.

API Key Retrieval

Once your account is activated:

1. Log in to your dashboard: Access your IPGEO account dashboard using your newly created credentials.
2. Locate API key: The API key is usually displayed prominently on the dashboard or under a section labeled 'API Keys', 'Settings', or 'Developer'. IPGEO automatically generates a key upon account creation as described in the IPGEO documentation.
3. Copy your API key: Securely copy this key. It is a sensitive credential and should be treated like a password. Do not hardcode it directly into client-side code or publicly expose it. For server-side applications, use environment variables or a secrets management system such as Google Cloud Key Management Service.

Your first request

With your API key in hand, you are ready to make your first request to the IPGEO API. The core functionality involves querying an IP address to retrieve its associated geolocation data. This example demonstrates a basic IP lookup for a specified IP address using cURL, a common command-line tool for making HTTP requests.

API Endpoint

The primary endpoint for IP geolocation is:

https://api.ipgeo.io/api/v1/ip/{IP_ADDRESS}?token={YOUR_API_KEY}

Replace {IP_ADDRESS} with the IP address you wish to query, and {YOUR_API_KEY} with the API key obtained from your dashboard.

Example Request (cURL)

Open your terminal or command prompt and execute the following cURL command. For demonstration, we'll use a public IP address like 8.8.8.8 (Google's public DNS server).

curl "https://api.ipgeo.io/api/v1/ip/8.8.8.8?token=YOUR_API_KEY"

Note: Replace YOUR_API_KEY with your actual API key.

Example Response (JSON)

A successful request will return a JSON object similar to this (data may vary):

{
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code2": "US",
  "country_code3": "USA",
  "country_name": "United States",
  "country_capital": "Washington D.C.",
  "state_prov": "California",
  "district": "Santa Clara",
  "city": "Mountain View",
  "zipcode": "94043",
  "latitude": "37.422",
  "longitude": "-122.084",
  "is_eu": false,
  "calling_code": "+1",
  "country_tld": ".us",
  "languages": "en-US,es-US,haw,fr",
  "isp": "Google LLC",
  "organization": "Google LLC",
  "asn": "AS15169",
  "timezone": {
    "id": "America/Los_Angeles",
    "abbr": "PDT",
    "utc": "-07:00"
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar"
  },
  "security": {
    "is_proxy": false,
    "proxy_type": null,
    "is_vpn": false,
    "vpn_type": null,
    "is_tor": false,
    "is_relay": false,
    "threat_level": "low"
  }
}

This response provides detailed information about the IP address, including geographical location, ISP, and security flags like VPN or proxy detection as detailed in the IPGEO API reference.

Quick Reference Table: Your First Request

Common next steps

After successfully making your first IPGEO API call, consider these next steps to further integrate and optimize your usage:

• Explore other endpoints: While the basic IP lookup is fundamental, IPGEO also offers a VPN/Proxy Detection API, which can be crucial for fraud detection or content restriction. Review the IPGEO documentation for details on available endpoints and their specific parameters.
• Implement in your application: Translate the cURL example into your preferred programming language. IPGEO provides examples in Python, PHP, and JavaScript. Libraries like requests in Python, Guzzle in PHP, or the native fetch API in JavaScript can simplify HTTP request handling.
• Error handling: Implement robust error handling in your application. The API will return specific HTTP status codes and JSON error messages for invalid requests, rate limit breaches, or authentication failures. Handling these gracefully will improve your application's reliability.
• Manage API key securely: Ensure your API key is not hardcoded into your application's source code, especially for public repositories. Utilize environment variables, secret management services, or configuration files that are not committed to version control.
• Monitor usage: Keep track of your API usage through the IPGEO dashboard to stay within your free tier limits or your chosen paid plan. This helps prevent unexpected service interruptions due to rate limiting.
• Consider advanced features: If your application requires more granular control or additional data points (e.g., historical data, more detailed network information), explore if IPGEO's paid plans offer these or consider how to combine IPGEO data with other services.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to help diagnose and resolve common problems:

• Invalid API Key:
  • Symptom: HTTP 401 Unauthorized or similar error message indicating an invalid token.
  • Solution: Double-check that you've copied your API key correctly from your IPGEO dashboard. Ensure there are no leading or trailing spaces.
• Incorrect Endpoint URL:
  • Symptom: HTTP 404 Not Found error.
  • Solution: Verify that the URL matches the official IPGEO API endpoint exactly, including the /api/v1/ip/ path and the correct IP address format.
• Missing IP Address:
  • Symptom: HTTP 400 Bad Request if the IP address segment of the URL is empty or malformed.
  • Solution: Ensure you are providing a valid IP address in the URL path, e.g., .../ip/8.8.8.8?....
• Rate Limit Exceeded:
  • Symptom: HTTP 429 Too Many Requests error.
  • Solution: If you are on the free tier (1,000 requests/day), you might have hit your limit. Wait for the next usage cycle or consider upgrading your plan. Review your dashboard for current usage statistics.
• Network Connectivity Issues:
  • Symptom: Connection timeouts or host unreachable errors.
  • Solution: Check your internet connection. If you are behind a corporate firewall, ensure that requests to api.ipgeo.io are not blocked.
• JSON Parsing Errors:
  • Symptom: Your application fails to parse the API response.
  • Solution: Verify that the API returned a valid JSON structure. Tools like browser developer tools or online JSON validators can help confirm the response format. Ensure your parsing library is configured correctly.