API Access

Getting Started

The Global City Explorer API provides access to our comprehensive database of city information, including population data, geographic coordinates, climate information, and more.

Base URL

API Versions

• v1: Current stable version
• beta: Experimental features

Authentication

All API requests require authentication using an API key. You can obtain an API key by signing up for an account on our platform.

How to Authenticate

Include your API key in the header of each request:

API Key Management

• Generate API keys from your account dashboard
• Revoke API keys at any time
• Set permissions for each API key
• Monitor API key usage and analytics

API Endpoints

The Global City Explorer API provides the following endpoints:

Rate Limits

To ensure fair usage and system stability, the Global City Explorer API has rate limits in place.

Rate Limit Tiers

Rate Limit Headers

API responses include the following headers to help you monitor your rate limit usage:

• X-RateLimit-Limit: The maximum number of requests allowed per minute
• X-RateLimit-Remaining: The number of requests remaining in the current window
• X-RateLimit-Reset: The timestamp when the rate limit window will reset

Response Formats

The Global City Explorer API returns responses in JSON format by default.

Success Response Example

{
  "status": "success",
  "data": {
    "id": 12345,
    "name": "New York",
    "country": "United States",
    "country_code": "US",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "population": 8336817,
    "area": 783.84,
    "timezone": "America/New_York",
    "currency": "USD",
    "language": "English"
  },
  "metadata": {
    "timestamp": 1717248000,
    "request_id": "abc123"
  }
}

Error Response Example

{
  "status": "error",
  "message": "City not found",
  "code": 404,
  "metadata": {
    "timestamp": 1717248000,
    "request_id": "def456"
  }
}

Error Codes

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing API key
• 404 Not Found: Requested resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Code Examples

Here are some examples of how to use the Global City Explorer API in different programming languages:

const apiKey = 'YOUR_API_KEY';
const cityId = 12345;

fetch(`https://api.globalcityexplorer.com/v1/cities/${cityId}`, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => response.json())
.then(data => {
  console.log('City data:', data);
})
.catch(error => {
  console.error('Error:', error);
});

import requests

api_key = 'YOUR_API_KEY'
city_id = 12345

url = f'https://api.globalcityexplorer.com/v1/cities/{city_id}'
headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
data = response.json()
print('City data:', data)

Frequently Asked Questions