Earth API Documentation
Quick Jump
🌍 Earth API Documentation
Comprehensive geographic and location data API
🌍 About Earth API
Earth API provides comprehensive geographic and location data including countries, states, cities, and IP geolocation services.
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:
- • Open ChatGPT, Claude, or your preferred LLM
- • Upload the downloaded JSON file
- • 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
Download & Save the Spec
- • Click "Download For LLM" button above
- • Save the
earth-api-docs-YYYY-MM-DD.jsonfile - • Keep it accessible for your tools
Choose Your Integration Method
For LLMs:
Upload directly to get instant help
For Development:
Import into your IDE or tools
Get Your API Key
🔑 Remember: You'll need an API key from your Dashboard to make actual API calls.
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
Earth API Base URL: Public Endpoints: 🎯 API Tiers & Rate Limits
🌍 Free Tier Endpoints
Free, Paid, Premium📋 List All Countries API Endpoint
Retrieve a comprehensive list of all countries worldwide with ISO codes, phone codes, and optional pagination for states and cities. Perfect for populating country dropdown menus, building location selectors, or creating geographic databases for e-commerce applications.
Use Case Example: An e-commerce website needs to populate a country selection dropdown during checkout. This endpoint provides all 195+ countries with ISO codes for address validation and shipping calculations.
List countries
GETParameters
cURL Command
🔍 Get Country Details by ID
Fetch detailed information about a specific country using its unique database ID. Returns comprehensive country data including ISO codes, phone codes, currency information, and optionally nested states and cities data with pagination support.
Use Case Example: A travel booking platform stores country IDs in user profiles. When displaying trip recommendations, they use this endpoint to fetch complete country details and associated cities for destination suggestions.
Get country by ID
GETParameters
cURL Command
🌐 Country Lookup by ISO2 Code
Retrieve country information using standard 2-letter ISO country codes (ISO 3166-1 alpha-2). Essential for international applications that need to convert country codes to full country data, validate addresses, or display localized content based on country codes.
Use Case Example: A payment processor receives "US" as a country code from credit card data and needs to validate the full country name, get the phone code (+1), and determine tax regulations for the United States.
Get country by ISO2 code
GETParameters
cURL Command
🗺️ Country Data by ISO3 Code
Access comprehensive country information using 3-letter ISO codes (ISO 3166-1 alpha-3). Ideal for applications working with international standards, banking systems, or government databases that commonly use 3-letter country codes for official documentation and data exchange.
Use Case Example: An international banking application processes SWIFT messages containing "USA" country codes and needs to convert them to full country details for compliance reporting and customer address verification.
Get country by ISO3 code
GETParameters
cURL Command
🏛️ Get States and Provinces by Country
Retrieve all states, provinces, or administrative divisions for a specific country. Essential for address forms, shipping calculators, and location-based services that need accurate administrative boundaries. Supports pagination and optional city data for each state.
Use Case Example: A real estate website allows users to browse properties by state. When a user selects "United States," this endpoint provides all 50 states plus DC for property filtering and location-based search functionality.
States by country
GETParameters
cURL Command
🏙️ Find State Information by City
Discover which state or province a specific city belongs to. Perfect for address validation, reverse geocoding, or when you have city information but need to determine the correct administrative division for shipping, taxation, or legal compliance purposes.
Use Case Example: A logistics company receives a shipping address with only the city "Chicago" and needs to automatically determine it's in Illinois state for accurate shipping calculations and delivery routing optimization.
State by city
GETParameters
cURL Command
🗳️ State Details by Database ID
Get comprehensive information about a specific state or province using its unique database identifier. Includes state name, country relationship, and optionally all cities within that state with pagination support for large datasets.
Use Case Example: A job board platform stores state IDs for job locations. When displaying job details, they use this endpoint to show the complete state information and nearby cities for job seekers looking for opportunities in that region.
Get state by ID
GETParameters
cURL Command
📜 Complete Global States Directory
Access a comprehensive directory of all states, provinces, and administrative divisions worldwide. With over 5,000 states across 195+ countries, this endpoint is perfect for building complete geographic databases, data analysis, or comprehensive location selectors.
Use Case Example: A global weather service needs to create a complete database of all administrative regions worldwide for accurate weather reporting and location-based weather alerts across different states and provinces.
List all states
GETParameters
cURL Command
🏘️ Cities Directory by Country
Retrieve all cities within a specific country with pagination support. Essential for travel applications, delivery services, or any platform requiring comprehensive city listings for address validation, location selection, or geographic analysis within country boundaries.
Use Case Example: A food delivery app expanding to Canada needs all Canadian cities to determine service areas, set up delivery zones, and calculate shipping costs for different municipal regions across the country.
Cities by country
GETParameters
cURL Command
🌆 Cities Within State or Province
Get all cities within a specific state or province. Perfect for regional business directories, local service platforms, or applications that need precise city-level data within administrative boundaries for targeted marketing or service delivery.
Use Case Example: A regional marketing agency targeting California businesses needs all cities in California to create location-specific advertising campaigns and analyze market penetration across different metropolitan areas.
Cities by state
GETParameters
cURL Command
🌍 Global Cities Database
Access our complete database of 150,000+ cities worldwide with pagination support. Ideal for building comprehensive location databases, global business directories, or any application requiring complete geographic coverage for international operations and data analysis.
Use Case Example: A global logistics company needs to build a complete database of all cities worldwide for their shipping calculator, route optimization, and international delivery network planning across multiple continents.
List all cities
GETParameters
cURL Command
🔍 Paid Tier Endpoints
Paid, Premium🔎 Advanced Country Search API
Powerful search functionality to find countries by name, phone code, or other attributes using fuzzy matching algorithms. Essential for autocomplete features, intelligent address forms, and dynamic country selection with real-time search capabilities and typo tolerance.
Use Case Example: An international calling app allows users to type "united" and instantly finds "United States," "United Kingdom," and "United Arab Emirates" with phone codes for easy country selection during number input.
Search countries
GETParameters
cURL Command
🏛️ Intelligent State Search Engine
Search through 5,000+ states and provinces globally using partial names, abbreviations, or keywords. Perfect for address autocomplete, regional business search, or location-based filtering with support for country-specific filtering and fuzzy text matching.
Use Case Example: A real estate platform allows users to search "calif" and immediately shows "California" along with all its cities, helping users quickly find properties in their desired state without exact spelling.
Search states
GETParameters
cURL Command
🌆 Global City Search API
Search through 150,000+ cities worldwide with advanced filtering by country, state, and intelligent text matching. Essential for travel booking, delivery services, business directories, and any application requiring accurate city identification with geographic context and hierarchy.
Use Case Example: A travel booking site lets users search "paris" and shows "Paris, France" and "Paris, Texas" with state/country context, helping travelers book the correct destination with geographic disambiguation.
Search cities
GETParameters
cURL Command
🌐 IP Geolocation Lookup Service
Convert IP addresses to precise geographic locations including country, state, city, coordinates, ISP information, and connection type. Essential for fraud detection, content personalization, security analysis, and location-based access control with IPv4 and IPv6 support.
Use Case Example: An e-commerce platform detects suspicious login from IP 8.8.8.8, uses geolocation to identify it's from Mountain View, CA (Google) and automatically allows the connection while logging the location for security analysis.
IP lookup (single)
GETParameters
cURL Command
📍 Reverse Geocoding - Countries by Coordinates
Find countries within a specified radius of geographic coordinates (latitude/longitude). Perfect for mobile apps, location-based services, border detection, and geographic analysis requiring proximity-based country identification with customizable search radius.
Use Case Example: A GPS navigation app at coordinates 40.7128°N, 74.0060°W (New York) uses this endpoint to identify it's in the United States and nearby countries within 100km for international roaming notifications.
Countries by coordinates
GETParameters
cURL Command
👤 Account Management
All Tiers📊 Real-Time Account Usage Statistics
Monitor your API usage in real-time including request counts, rate limit status, subscription tier information, remaining quota, and billing period details. Essential for usage monitoring, cost control, and ensuring optimal API utilization within your plan limits.
Use Case Example: A development team monitors their account usage daily to track API consumption against their premium tier limits, receiving alerts when approaching monthly quotas to prevent service interruptions.
Account usage stats
GETcURL Command
🌐 Public Endpoints
No Auth Required🌍 Global Countries Database Statistics
Get the total count of countries available in our database without authentication. Perfect for displaying database statistics, validating API connectivity, or building dynamic content that references our geographic coverage with up-to-date country counts.
Countries count
GETcURL Command
⚡ API Health & Status Monitor
Check real-time API health, response times, and service availability without authentication. Essential for monitoring integrations, status page widgets, uptime monitoring, and ensuring API availability before making authenticated requests in production environments.
API status
GETcURL Command
ℹ️ API Version & Information Service
Retrieve comprehensive API information including version details, supported features, rate limits, and service capabilities without authentication. Perfect for API discovery, version compatibility checks, and displaying service information in developer dashboards or documentation.
Use Case Example: A developer integration wizard automatically checks API info to verify version compatibility, display available features, and configure appropriate rate limiting based on the current API capabilities and specifications.
API information
GETcURL Command
🚀 Quick Start Examples
Get all US states:
GET /earth/v1/country/iso2/US?paginate_states=trueSearch for cities named "Paris":
GET /earth/v1/cities/search?q=parisIP Geolocation lookup:
GET /earth/v1/ip/lookup/8.8.8.8Get API status (public):
GET /earth/v1/public/status🌍 Earth API v1.0 - Comprehensive geographic and location data services. Use the parameter controls above each section to customize requests before testing.