GeoJS Getting Started: IP Geolocation API Quickstart (2026)

Getting started overview

GeoJS offers a RESTful API designed for IP geolocation, providing data such as country, city, and coordinates based on an IP address. The service emphasizes ease of use and quick integration, making it suitable for projects requiring immediate access to IP-based geographical information. This guide outlines the necessary steps to initiate usage: account creation, understanding API access, and performing a basic request to retrieve geolocation data.

GeoJS provides a free tier of 1,500 requests per hour, which does not require an API key for basic usage. For higher volumes or dedicated support, paid plans are available, starting at $10 per month for 500,000 requests per month. While an API key is not strictly mandatory for the free tier, it is recommended for tracking usage and accessing specific features or higher rate limits associated with paid plans.

The core functionality revolves around its IP Geolocation API, which can be accessed via simple HTTP GET requests. Responses are typically provided in JSON format, facilitating parsing and integration into various programming environments. The API supports both IPv4 and IPv6 addresses.

Here's a quick overview of the steps involved:

Create an account and get keys

While GeoJS allows basic IP geolocation lookups without an API key for its free tier, creating an account is beneficial for monitoring usage, upgrading to paid plans, and accessing features that may require authentication. If you intend to use GeoJS beyond the anonymous free tier or require usage tracking, follow these steps:

1. Visit the GeoJS Website: Navigate to the official GeoJS homepage.
2. Sign Up: Look for a "Sign Up" or "Get Started" button. You will typically be prompted to provide an email address and create a password.
3. Verify Email: After signing up, check your email for a verification link to confirm your account.
4. Access Dashboard: Once verified, log in to your GeoJS dashboard.
5. Locate API Key: Within your dashboard, you should find your unique API key. GeoJS simplifies this by often displaying it prominently or under a "API Keys" or "Settings" section. For the free tier, if you choose not to create an account, no key is needed for basic requests. However, for paid plans, this key is essential for authentication and accessing higher rate limits.

It is important to keep your API key secure and avoid exposing it in client-side code or public repositories. If you suspect your key has been compromised, GeoJS typically provides options within your dashboard to regenerate it.

Your first request

The GeoJS API is designed for simplicity. For basic IP geolocation, you can make a direct HTTP GET request to its public endpoints. No API key is required for the free tier, making the first request straightforward. The primary endpoint for retrieving client IP information is https://get.geojs.io/v1/ip/geo.json.

Using cURL (Command Line)

To test the API quickly from your terminal, use cURL:

curl https://get.geojs.io/v1/ip/geo.json

This command will return a JSON object containing geolocation data for the IP address from which the request originated. An example response might look like this:

{
  "ip": "8.8.8.8",
  "continent_code": "NA",
  "country": "United States",
  "region": "California",
  "city": "Mountain View",
  "latitude": "37.4220",
  "longitude": "-122.0841",
  "timezone": "America/Los_Angeles",
  "organization_name": "Google LLC"
}

To specify a different IP address, you can append it to the URL:

curl https://get.geojs.io/v1/ip/8.8.4.4/geo.json

Using JavaScript (Browser or Node.js)

In a web browser, you can make a request using the fetch API:

fetch('https://get.geojs.io/v1/ip/geo.json')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error fetching geolocation:', error));

For Node.js environments, you might use a library like axios or the built-in https module:

const https = require('https');

https.get('https://get.geojs.io/v1/ip/geo.json', (resp) => {
  let data = '';

  resp.on('data', (chunk) => {
    data += chunk;
  });

  resp.on('end', () => {
    console.log(JSON.parse(data));
  });

}).on('error', (err) => {
  console.error('Error: ' + err.message);
});

Using Python

Python's requests library simplifies HTTP requests:

import requests

response = requests.get('https://get.geojs.io/v1/ip/geo.json')
if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")

These examples demonstrate how to retrieve geolocation data for the requesting IP address. For more detailed examples and language-specific implementations, refer to the GeoJS documentation.

Common next steps

After successfully making your first request to GeoJS, consider these common next steps to integrate the API more fully into your application or explore its capabilities:

1. Error Handling: Implement robust error handling in your code. The API will return appropriate HTTP status codes (e.g., 400 for bad requests, 403 for forbidden) and often include error messages in the JSON response. Understanding these can help diagnose issues and provide a better user experience. Developers can review common HTTP status codes and their meanings in resources like the Mozilla Developer Network HTTP status code reference.
2. Parse and Utilize Data: Extract the specific fields you need from the JSON response (e.g., country, city, latitude, longitude). Integrate this data into your application logic. For instance, you might use the coordinates to display a user's location on a map using a mapping library like Google Maps or OpenLayers.
3. Rate Limits and Usage Monitoring: If you're using the free tier, be mindful of the 1,500 requests per hour limit. For paid plans, monitor your usage through the GeoJS dashboard to ensure you stay within your plan's limits. Excessive requests can lead to temporary blocking or additional charges.
4. API Key Integration (for paid plans or tracking): If you've signed up for a paid plan or wish to track your free tier usage, ensure your API key is included in your requests. While GeoJS documentation may not explicitly detail API key usage for all endpoints, it's generally passed as a query parameter or HTTP header for authenticated requests. Consult your GeoJS dashboard or specific documentation for details on how to use your key.
5. Explore Additional Endpoints: GeoJS may offer other endpoints beyond basic IP geolocation. Review the GeoJS API reference to discover features like IP address validation or specific data lookups.
6. Security Considerations: When using any external API, consider security. If your application handles sensitive user data, ensure all communications are over HTTPS (which GeoJS endpoints already enforce). Protect your API keys by storing them securely and never hardcoding them directly into client-side code or public repositories.
7. Client Libraries (if available): While GeoJS is straightforward to use with raw HTTP requests, some developers prefer using dedicated client libraries for their programming language. Check the GeoJS documentation or community resources for any officially supported or community-maintained SDKs that might simplify integration further.

Troubleshooting the first call

Encountering issues during your initial API call is common. Here's a guide to troubleshooting common problems when interacting with GeoJS:

1. Incorrect Endpoint URL:
   • Symptom: HTTP 404 Not Found error or an unexpected response.
   • Solution: Double-check the URL against the GeoJS API reference. Ensure there are no typos, missing slashes, or incorrect domain names. The primary endpoint for client IP geolocation is https://get.geojs.io/v1/ip/geo.json.
2. Network Connectivity Issues:
   • Symptom: Request timeouts or connection refused errors.
   • Solution: Verify your internet connection. Try accessing https://get.geojs.io/v1/ip/geo.json directly in a web browser to see if you receive a response. Check if any firewalls or network proxies are blocking outbound connections to geojs.io.
3. Invalid JSON Response (Parsing Errors):
   • Symptom: Your code fails to parse the API response, reporting "unexpected token" or "invalid JSON."
   • Solution: The GeoJS API typically returns valid JSON. If you're encountering parsing issues, it might be due to an error response (e.g., HTML error page from a proxy) or an incomplete response. Print the raw response body to inspect its content before attempting to parse it as JSON.
4. Rate Limit Exceeded (HTTP 429 Too Many Requests):
   • Symptom: You receive an HTTP 429 status code.
   • Solution: This indicates you've exceeded the free tier's 1,500 requests per hour limit or your current plan's limit. Wait for the rate limit to reset, or consider upgrading to a paid GeoJS plan for higher request volumes. Implement client-side rate limiting or caching mechanisms to reduce the number of API calls.
5. Incorrect API Key (if applicable):
   • Symptom: HTTP 401 Unauthorized or 403 Forbidden errors, especially if you're on a paid plan or using a key for tracking.
   • Solution: Ensure your API key is correctly included in the request, if required by your plan or specific endpoint. Verify the key in your GeoJS dashboard. If you recently regenerated it, ensure you're using the latest version.
6. CORS Issues (for browser-based requests):
   • Symptom: "No 'Access-Control-Allow-Origin' header is present" error in browser console.
   • Solution: GeoJS generally supports CORS for its public endpoints. If you encounter this, ensure your browser is not blocking requests due to extensions or security settings. If making requests from an unusual origin, confirm GeoJS supports cross-origin requests from that domain. For backend requests, CORS is not a concern.
7. Outdated Documentation/Examples:
   • Symptom: Examples from older resources don't work.
   • Solution: Always refer to the official GeoJS documentation for the most up-to-date API endpoints and usage instructions.

When troubleshooting, it's often helpful to print the full HTTP request (headers and body) and the full HTTP response (status code, headers, and body). This provides complete context for diagnosing the issue.