Keshtay API Logo

Earth Geolocation API

Sign in to access your API dashboard

Forgot password?

Don't have an account?

Professional IP Geolocation & Analytics

Enterprise-grade APIs with comprehensive dashboards, real-time monitoring, and flexible pricing tiers

IP Geolocation API

Accurate IP-to-location mapping with comprehensive geographic data including country, region, city, coordinates.

  • 99.9% accuracy for country detection
  • Single & batch IP lookup support

Real-time Analytics

Comprehensive usage analytics with detailed request history, performance metrics, and geographic insights for all your API calls.

  • Real-time request monitoring
  • Geographic usage insights
  • Performance & error tracking

Comprehensive Dashboard

Professional dashboard with API key management, usage monitoring, subscription control.

  • API key management & rotation
  • Usage limits & notifications
  • Subscription tier management

Complete Geographic Data

Access comprehensive country, state, and city information with coordinates, translations, and hierarchical relationships.

  • 195+ countries with detailed info
  • 5,000+ states & regions covered
  • 150,000+ cities with coordinates

Flexible Subscription Tiers

Choose from Free, Paid, and Premium tiers with different request limits, features, and analytics capabilities. Easy upgrades and downgrades.

  • Free tier with 1,000 requests/month
  • No setup fees or hidden costs
  • Cancel or upgrade anytime

Enterprise-Grade Support

Professional support with comprehensive documentation, interactive examples, and dedicated assistance for enterprise customers.

  • Comprehensive API documentation
  • Interactive code examples
  • Priority email & chat support

Perfect for Every Use Case

From fraud prevention to content localization - our IP geolocation API powers it all

Security & Fraud Prevention

Detect suspicious activities, prevent fraud, and implement location-based security measures with accurate IP geolocation data.

Content Localization

Deliver personalized content based on user location, show relevant products, and customize experiences for different regions.

Analytics & Business Intelligence

Enhance business intelligence with geographic insights, user demographics, and location-based analytics for better decision making.

E-commerce & Payments

Streamline checkout with address validation, tax calculations, shipping estimates, and payment fraud detection based on location.

Mobile & Web Applications

Build location-aware apps with user registration forms, store locators, geo-targeted advertising, and location-based services.

Compliance & Regulations

Ensure GDPR compliance, implement geo-blocking, manage data sovereignty requirements, and meet regional regulations.

AI-Powered Development
Copy, Paste, and Go Live in Minutes

Our OpenAPI 3.1 specification makes integration effortless. Upload to any LLM (ChatGPT, Claude, GitHub Copilot) and get instant, production-ready code in your preferred programming language.

LLM-Ready OpenAPI Spec

Download our complete OpenAPI 3.1 specification and upload it to any AI coding assistant:

How to Use the OpenAPI Spec

The downloaded OpenAPI JSON specification contains complete documentation of our Earth API. Use it with various tools and LLMs for integration, testing, and development.

1
LLM Integration (ChatGPT, Claude, etc.)

πŸ“€ Upload to LLM:

  1. β€’ Open ChatGPT, Claude, or your preferred LLM
  2. β€’ Upload the downloaded JSON file
  3. β€’ Ask: "Help me integrate with this API"

Example Prompts:

  • β€’ "Generate Python code to get country data"
  • β€’ "Create a JavaScript client for IP lookup"
  • β€’ "Show me the authentication requirements"

2
Development Tools

πŸ› οΈ Code Generation:

  • β€’ Swagger Codegen: Generate client SDKs
  • β€’ OpenAPI Generator: Create API clients
  • β€’ Postman: Import for testing

Quick Commands:

# Generate Python client
openapi-generator-cli generate \
  -i earth-api-docs.json \
  -g python \
  -o ./earth-api-client

πŸ“‹ Step-by-Step Usage Guide

1
Download & Save the Spec
  • β€’ Click "Download For LLM" button above
  • β€’ Save the earth-api-docs-YYYY-MM-DD.json file
  • β€’ Keep it accessible for your tools
2
Choose Your Integration Method

For LLMs:

Upload directly to get instant help

For Development:

Import into your IDE or tools

3
Get Your API Key

πŸ”‘ Remember: You'll need an API key from your Dashboard to make actual API calls.

4
Start Building
  • β€’ Use the spec to understand endpoints and parameters
  • β€’ Generate client code or make manual requests
  • β€’ Test with your API key in the Authorization header
  • β€’ Refer back to this documentation for examples

πŸ”§ Popular Tools That Support OpenAPI

Testing Tools
  • β€’ Postman
  • β€’ Insomnia
  • β€’ Thunder Client (VS Code)
  • β€’ Swagger UI
Code Generation
  • β€’ OpenAPI Generator
  • β€’ Swagger Codegen
  • β€’ NSwag Studio
  • β€’ AutoRest
AI Assistants
  • β€’ ChatGPT
  • β€’ Claude
  • β€’ GitHub Copilot
  • β€’ Cursor AI
πŸ’‘ Pro Tips
  • β€’ The spec includes all endpoint details, parameters, and response schemas
  • β€’ Look for "x-tier-required" in the spec to understand tier requirements
  • β€’ Rate limiting information is included in the response headers section
  • β€’ Use the examples in the spec as starting points for your requests

Download Options

ChatGPT Compatible
Claude Ready
GitHub Copilot
Cursor AI

⚑ Instant Code Generation

Upload our OpenAPI spec to any LLM and get production-ready integration code in seconds:

Python (requests, aiohttp)
JavaScript (fetch, axios)
PHP (cURL, Guzzle)
Node.js, Go, Ruby, C#

Integration in 3 Simple Steps

1

Download OpenAPI Spec

Click the download button above to get our complete API specification in OpenAPI 3.1 format.

2

Upload to Your LLM

Upload the JSON file to ChatGPT, Claude, or any AI assistant and ask: "Generate integration code for this API"

3

Copy, Paste & Deploy

Get ready-to-use code with error handling, authentication, and best practices. Just add your API key!

Don't forget: Register for a free API key to start making requests!

πŸ€– Example: What LLMs Generate from Our OpenAPI Spec

Upload our spec and ask: "Generate Python code to get IP location data"

Python 
import requests

def get_ip_location(ip_address, api_key):
    """Get IP geolocation data"""
    url = "https://api.keshtay.com/earth/v1/ip/lookup"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json"
    }
    params = {"ip": ip_address}
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Usage
location = get_ip_location("8.8.8.8", "your-api-key")
JavaScript 
async function getIPLocation(ipAddress, apiKey) {
    const response = await fetch(
        `https://api.keshtay.com/earth/v1/ip/lookup?ip=${ipAddress}`,
        {
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Accept': 'application/json'
            }
        }
    );
    return await response.json();
}

// Usage
const location = await getIPLocation('8.8.8.8', 'your-api-key');

LLMs automatically generate: Error handling, TypeScript definitions, async/await patterns, authentication headers, request validation, and response parsing, all from our OpenAPI specification!

Works with Every Framework & Platform

React
Frontend
Vue.js
Frontend
Laravel
PHP
Django
Python
Express.js
Node.js
Spring Boot
Java

Plus: .NET Core, Ruby on Rails, Go (Gin/Echo), Rust (Actix/Axum), and any framework that supports HTTP requests

Transparent Pricing, No Hidden Fees

Choose the plan that fits your needs. Start free and scale as you grow. 30-day notice for any pricing changes.

Choose Your Plan

free plan
FREE
  • 10 requests/min
  • 100 requests/day
  • 1,000 requests/month
  • Countries, States & Cities data
  • ISO2/ISO3 country lookup
  • Advanced search capabilities PAID
  • IP geolocation lookup PAID
  • Coordinate-based country search PAID
  • Batch IP lookup (multiple IPs) PREMIUM
  • Full country hierarchy data PREMIUM
  • Location insights & analytics PREMIUM
  • Coordinate-based city/state search PREMIUM
  • IP lookup history PREMIUM
  • Complete API documentation
  • Email support
  • Usage analytics dashboard PAID
Login to Subscribe
paid plan
$ 6 /month
$15.00
Save 60%
  • 60 requests/min
  • 5,000 requests/day
  • 100,000 requests/month
  • Countries, States & Cities data
  • ISO2/ISO3 country lookup
  • Advanced search capabilities
  • IP geolocation lookup
  • Coordinate-based country search
  • Batch IP lookup (multiple IPs) PREMIUM
  • Full country hierarchy data PREMIUM
  • Location insights & analytics PREMIUM
  • Coordinate-based city/state search PREMIUM
  • IP lookup history PREMIUM
  • Complete API documentation
  • Email support
  • Usage analytics dashboard
Login to Subscribe
premium plan
$ 18 /month
$25.00
Save 28%
  • 300 requests/min
  • 50,000 requests/day
  • 1,000,000 requests/month
  • Countries, States & Cities data
  • ISO2/ISO3 country lookup
  • Advanced search capabilities
  • IP geolocation lookup
  • Coordinate-based country search
  • Batch IP lookup (multiple IPs)
  • Full country hierarchy data
  • Location insights & analytics
  • Coordinate-based city/state search
  • IP lookup history
  • Complete API documentation
  • Priority support
  • Usage analytics dashboard
Login to Subscribe

Optional Auto-Billing for Overages

Never worry about hitting your limits again. Enable automatic billing to keep your service running seamlessly when you exceed your plan's usage caps.

Daily Overage Billing

When you exceed your daily request limit, auto-billing charges approximately 1/30th of your monthly plan cost for that day's additional usage.

Example: $30/month plan = ~$1.00/day overage

Monthly Overage Billing

When you exceed your monthly limit, auto-billing immediately resets your billing cycle and charges you for a full new month of service.

Example: Your limits refresh instantly with a new billing period
Requirements & Important Notes
  • β€’ Default payment method required: Must have a valid credit card saved to your account
  • β€’ Optional feature: Auto-billing is disabled by default and can be toggled in your account settings
  • β€’ Notification system: You'll receive email alerts before and after any overage charges

Auto-billing ensures uninterrupted service while giving you full control over your usage costs.

See It In Action

Sample responses from our Earth API endpoints - notice how data richness varies by tier

GET /api/earth/v1/countries

Per page:
Free Tier: Basic country data - Max 5 per page, 100 requests/day, 1,000/month 
{
  "status": "success",
  "message": "Success",
  "data": [
    {
      "id": 231,
      "name": "United States",
      "iso2": "US",
      "iso3": "USA"
    },
    {
      "id": 39,
      "name": "Canada", 
      "iso2": "CA",
      "iso3": "CAN"
    },
    {
      "id": 107,
      "name": "Germany",
      "iso2": "DE",
      "iso3": "DEU"
    },
    {
      "id": 74,
      "name": "France",
      "iso2": "FR",
      "iso3": "FRA"
    },
    {
      "id": 109,
      "name": "Italy",
      "iso2": "IT",
      "iso3": "ITA"
    }
  ],
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Paid Tier: Enhanced data with search - Max 50 per page, 5,000 requests/day, 100,000/month 
{
  "status": "success",
  "message": "Success",
  "data": [
    {
      "id": 231,
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "phonecode": "+1",
      "tld": ".us",
      "native": "United States",
      "emoji": "πŸ‡ΊπŸ‡Έ",
      "states_count": 51,
      "cities_count": 19369
    },
    {
      "id": 39,
      "name": "Canada",
      "iso2": "CA", 
      "iso3": "CAN",
      "phonecode": "+1",
      "tld": ".ca",
      "native": "Canada",
      "emoji": "πŸ‡¨πŸ‡¦",
      "states_count": 13,
      "cities_count": 7494
    }
  ],
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Premium Tier: Complete dataset with analytics - Max 100 per page, 50,000 requests/day, 1M/month 
{
  "status": "success",
  "message": "Success",
  "data": [
    {
      "id": 231,
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "phonecode": "+1",
      "tld": ".us",
      "native": "United States",
      "emoji": "πŸ‡ΊπŸ‡Έ",
      "latitude": 37.0902,
      "longitude": -95.7129,
      "states_count": 51,
      "cities_count": 19369,
      "states": [
        {
          "id": 1434,
          "name": "California",
          "country_id": 231,
          "latitude": 36.7783,
          "longitude": -119.4179,
          "cities_count": 1634
        },
        {
          "id": 1452,
          "name": "New York",
          "country_id": 231,
          "latitude": 42.9538,
          "longitude": -75.5268,
          "cities_count": 1654
        }
      ],
      "timezones": [
        "America/New_York",
        "America/Chicago", 
        "America/Denver",
        "America/Los_Angeles"
      ],
      "translations": {
        "de": "Vereinigte Staaten",
        "es": "Estados Unidos",
        "fr": "Γ‰tats-Unis",
        "ja": "をパγƒͺγ‚«εˆθ‘†ε›½",
        "ar": "Ψ§Ω„ΩˆΩ„Ψ§ΩŠΨ§Ψͺ Ψ§Ω„Ω…ΨͺΨ­Ψ―Ψ©"
      }
    }
  ],
  "timestamp": "2024-10-14T15:30:42.000000Z"
}

GET /api/earth/v1/ip/lookup/8.8.8.8

Access:
Free Tier: IP lookup not available - requires Paid tier or higher 
{
  "status": "error",
  "message": "IP geolocation requires paid subscription",
  "data": null,
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Paid Tier: Basic IP geolocation - Max 50 IPs per batch 
{
  "status": "success",
  "message": "Success", 
  "data": {
    "ip": "8.8.8.8",
    "zip_code": "94043",
    "country": {
      "id": 231,
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "phonecode": "+1",
      "tld": ".us",
      "native": "United States",
      "emoji": "πŸ‡ΊπŸ‡Έ"
    },
    "state": {
      "id": 1434,
      "name": "California",
      "country_id": 231
    },
    "city": {
      "id": 111543,
      "name": "Mountain View",
      "state_id": 1434,
      "country_id": 231
    },
  },
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Premium Tier: Enhanced IP intelligence with full analytics - Max 100 IPs per batch 
{
  "status": "success",
  "message": "Success",
  "data": {
    "ip": "8.8.8.8",
    "zip_code": "94043",
    "country": {
      "id": 231,
      "name": "United States",
      "iso2": "US",
      "iso3": "USA",
      "phonecode": "+1",
      "tld": ".us",
      "native": "United States",
      "emoji": "πŸ‡ΊπŸ‡Έ",
      "latitude": 37.0902,
      "longitude": -95.7129,
      "timezones": [
        "America/New_York",
        "America/Chicago",
        "America/Denver", 
        "America/Los_Angeles"
      ],
      "translations": {
        "de": "Vereinigte Staaten",
        "es": "Estados Unidos",
        "fr": "Γ‰tats-Unis"
      }
    },
    "state": {
      "id": 1434,
      "name": "California",
      "country_id": 231,
      "latitude": 36.7783,
      "longitude": -119.4179,
      "cities_count": 1634
    },
    "city": {
      "id": 111543,
      "name": "Mountain View",
      "state_id": 1434,
      "country_id": 231,
      "latitude": 37.4056,
      "longitude": -122.0775
    },
    "latitude": 37.4056,
    "longitude": -122.0775,
  },
  "timestamp": "2024-10-14T15:30:42.000000Z"
}

GET /api/earth/v1/cities/search?q=new york

Access:
Free Tier: Search functionality requires Paid tier or higher 
{
  "status": "error",
  "message": "Search functionality requires paid subscription",
  "data": null,
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Paid Tier: Basic search results - Max 50 results per page 
{
  "status": "success", 
  "message": "Success",
  "data": {
    "cities": [
      {
        "id": 111532,
        "name": "New York",
        "state_id": 1452,
        "country_id": 231,
        "state": {
          "id": 1452,
          "name": "New York",
          "country_id": 231
        },
        "country": {
          "id": 231,
          "name": "United States",
          "iso2": "US",
          "iso3": "USA"
        }
      },
      {
        "id": 111533,
        "name": "New York Mills",
        "state_id": 1424,
        "country_id": 231,
        "state": {
          "id": 1424,
          "name": "Minnesota",
          "country_id": 231
        },
        "country": {
          "id": 231,
          "name": "United States",
          "iso2": "US",
          "iso3": "USA"
        }
      }
    ]
  },
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Premium Tier: Enhanced search with full hierarchy data - Max 100 results per page 
{
  "status": "success",
  "message": "Success", 
  "data": {
    "cities": [
      {
        "id": 111532,
        "name": "New York",
        "state_id": 1452,
        "country_id": 231,
        "latitude": 40.7128,
        "longitude": -74.0060,
        "state": {
          "id": 1452,
          "name": "New York",
          "country_id": 231,
          "latitude": 42.9538,
          "longitude": -75.5268,
          "cities_count": 1654
        },
        "country": {
          "id": 231,
          "name": "United States",
          "iso2": "US",
          "iso3": "USA",
          "phonecode": "+1",
          "emoji": "πŸ‡ΊπŸ‡Έ",
          "latitude": 37.0902,
          "longitude": -95.7129
        },
        "timezone": "America/New_York"
      }
    ]
  },
  "timestamp": "2024-10-14T15:30:42.000000Z"
}

GET /api/earth/v1/analytics/usage-stats

Premium Only
Tier: Analytics API requires Premium tier subscription 
{
  "status": "error",
  "message": "Analytics API requires Premium tier",
  "data": null,
  "timestamp": "2024-10-14T15:30:42.000000Z"
}
Premium Tier: Comprehensive analytics with request patterns and performance metrics 
{
  "status": "success",
  "message": "Success",
  "data": {
    "period": "last_30_days",
    "total_requests": 45267,
    "successful_requests": 44891,
    "error_requests": 376,
    "success_rate": 99.17,
    "avg_response_time": 87,
    "unique_ips_queried": 12543,
    "unique_endpoints_used": 8,
    "data_transferred": "2.3 GB",
    "peak_hour": "14:00 UTC",
    "top_countries_queried": [
      {
        "country": "United States",
        "requests": 15432,
        "percentage": 34.1
      },
      {
        "country": "Canada", 
        "requests": 6789,
        "percentage": 15.0
      }
    ],
    "endpoint_usage": {
      "/api/earth/v1/ip/lookup": 28456,
      "/api/earth/v1/countries": 8901,
      "/api/earth/v1/cities/search": 4567,
      "/api/earth/v1/states": 3343
    },
    "daily_breakdown": [
      {
        "date": "2024-10-13",
        "requests": 1876,
        "errors": 12,
        "avg_response_time": 92
      }
    ]
  },
  "timestamp": "2024-10-14T15:30:42.000000Z"
}

API Feature Comparison by Tier

Feature Free Paid Premium
Requests Per Minute 10 60 300
Daily Requests 100 5,000 50,000
Monthly Requests 1,000 100,000 1,000,000
Max Pagination Per Request 5 50 100
IP Batch Processing βœ— No Access 50 IPs per batch 100 IPs per batch
Basic Geographic Data βœ“ Countries, States, Cities βœ“ Full Access βœ“ Full Access
ISO2/ISO3 Country Lookup βœ“ βœ“ βœ“
Search Functionality βœ— Not Available βœ“ Countries, States, Cities βœ“ Enhanced Search
IP Geolocation Lookup βœ— Not Available βœ“ Single IP βœ“ Single + Batch
Coordinate-Based Search βœ— βœ“ Countries Only βœ“ Countries, States, Cities
Full Hierarchy Data βœ— βœ— βœ“ Complete Nested Data
IP Lookup History βœ— βœ— βœ“ Full History Access
Location Insights & Analytics βœ— βœ— βœ“ Advanced Analytics
Usage Analytics API βœ— βœ— βœ“ Comprehensive Stats
Basic Account Usage Stats βœ“ βœ“ βœ“

Ready for More Power?

Unlock IP geolocation, advanced search, comprehensive analytics, and higher request limits by upgrading your tier.

Start Free Trial View Full API Docs