GeoDB Cities Getting Started: API Keys and First Request (2026)

Getting started overview

This guide provides a structured approach to initiating development with the GeoDB Cities API. It covers the necessary steps from account creation and API key retrieval to executing a foundational API request. The GeoDB Cities API delivers city-specific data, encompassing details such as populations, geographic coordinates, and timezone information, suitable for applications requiring location-based functionalities. This API is a RESTful service, meaning it uses standard HTTP methods for data operations, which is a common architectural style for web services explaining RESTful architecture.

The primary goal is to enable developers to make their initial API call successfully and to understand common follow-up steps and troubleshooting techniques. The GeoDB Cities API is designed for ease of integration, offering clear documentation and code examples across multiple programming languages.

Below is a quick reference table outlining the key steps:

Create an account and get keys

To access the GeoDB Cities API, you must first register for an account on the official GeoDB website. This process establishes your user profile and grants you access to the developer dashboard, where your API key is managed.

1. Navigate to the GeoDB Website: Open your web browser and go to the GeoDB homepage.
2. Sign Up for a New Account: Look for a 'Sign Up' or 'Get Started' button, typically located in the top right corner of the page. You will be prompted to provide an email address, create a password, and agree to the terms of service.
3. Verify Your Email: After submitting your registration details, GeoDB will send a verification email to the address you provided. Follow the instructions in this email to activate your account. This step is crucial for security and account integrity.
4. Access Your Dashboard: Once your email is verified, log in to your GeoDB account. This will take you to your personal developer dashboard.
5. Locate Your API Key: Within the dashboard, there will be a section dedicated to API keys or credentials. Your unique API key will be displayed here. This key is essential for authenticating your API requests. It acts as a token that verifies your identity and authorization to use the service, a standard practice in API security as seen in OAuth 2.0 specifications.
6. Keep Your API Key Secure: Treat your API key as sensitive information. Do not embed it directly in client-side code, commit it to public repositories, or share it unnecessarily. If your key is compromised, you can typically regenerate it from your GeoDB dashboard.

GeoDB offers a free tier that includes 10,000 requests per month, which is sufficient for initial testing and small-scale applications. Paid plans are available for higher usage requirements, starting at $49 per month for 50,000 requests.

Your first request

Once you have your API key, you can make your first request to the GeoDB Cities API. This example demonstrates how to find information about a specific city using a basic HTTP GET request. We will use cURL for a command-line example, which is widely available across operating systems and useful for quick tests.

Example: Finding a city by name

The GeoDB Cities API allows you to search for cities based on various criteria. For this first request, we'll use the /cities endpoint to search for a city by its name.

Endpoint

GET https://wft-geo-db.p.rapidapi.com/v1/geo/cities

Parameters

• namePrefix: A string to match against city names.
• limit: The maximum number of results to return (e.g., 10).
• offset: The number of results to skip (e.g., 0).
• api_key: Your GeoDB API key.

cURL example

Replace YOUR_API_KEY with the actual API key you obtained from your GeoDB dashboard.

curl --request GET \
  --url 'https://wft-geo-db.p.rapidapi.com/v1/geo/cities?namePrefix=London&limit=10&offset=0' \
  --header 'x-rapidapi-host: wft-geo-db.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_API_KEY'

Expected JSON Response (partial example)

A successful request will return a JSON object containing an array of city data. The structure will typically include city name, country, latitude, longitude, and population details.

{
  "data": [
    {
      "id": 2643743,
      "wikiDataId": "Q84",
      "type": "CITY",
      "city": "London",
      "name": "London",
      "country": "United Kingdom",
      "countryCode": "GB",
      "region": "England",
      "regionCode": "ENG",
      "latitude": 51.507222222,
      "longitude": -0.1275,
      "population": 8908081
    },
    {
      "id": 4166946,
      "wikiDataId": "Q100",
      "type": "CITY",
      "city": "London",
      "name": "London",
      "country": "United States",
      "countryCode": "US",
      "region": "Kentucky",
      "regionCode": "KY",
      "latitude": 37.1289,
      "longitude": -84.083,
      "population": 7984
    }
  ],
  "metadata": {
    "currentOffset": 0,
    "totalCount": 20
  }
}

This response structure provides an array under the data key, with each element representing a city that matches the query. The metadata object offers information about the pagination of results.

JavaScript SDK example

GeoDB provides a JavaScript SDK to facilitate integration. This example shows how to achieve the same city search using the SDK.

import { GeoDb } from '@geodb/js-client';

const geoDb = new GeoDb('YOUR_API_KEY'); // Replace with your actual API key

async function findCity() {
  try {
    const response = await geoDb.findCities({
      namePrefix: 'London',
      limit: 10
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error fetching city data:', error);
  }
}

findCity();

To use the JavaScript SDK, you would typically install it via a package manager like npm: npm install @geodb/js-client.

Common next steps

After successfully making your first API call, consider these next steps to deepen your integration and explore the full capabilities of the GeoDB Cities API:

• Explore Additional Endpoints: The GeoDB Cities API offers various endpoints beyond simple city search. Review the API Reference documentation to discover how to retrieve city details, nearby cities, or specific data like timezones.
• Implement Autocomplete Search: Utilize the namePrefix parameter with dynamic user input to create an autocomplete search feature for city names, enhancing user experience in forms or search bars.
• Integrate with Your Application: Begin integrating the API calls into your actual application logic. Consider how you will handle user input, display results, and manage pagination for larger datasets.
• Error Handling: Implement robust error handling in your code to gracefully manage API response errors, network issues, or invalid requests. The GeoDB API generally uses standard HTTP status codes to indicate success or failure.
• Monitor Usage: Regularly check your API usage statistics within your GeoDB dashboard to stay within your plan's limits and monitor performance.
• Secure Your API Key: Ensure that your API key is not exposed in client-side code or public repositories. For server-side applications, store it as an environment variable or in a secure configuration management system.
• Review SDKs and Libraries: If you're using a language other than JavaScript, check the GeoDB documentation for community-contributed SDKs or examples in Python, PHP, Ruby, Java, or Go.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• 401 Unauthorized / Invalid API Key: If you receive a 401 status code, it usually means your API key is missing, incorrect, or expired. Double-check that you've copied the key accurately from your GeoDB dashboard and that it's included correctly in your request headers (e.g., x-rapidapi-key). Ensure there are no leading or trailing spaces.
• 403 Forbidden / Rate Limit Exceeded: A 403 error can indicate that your account doesn't have the necessary permissions for the requested action or that you've exceeded your plan's rate limits. Verify your subscription tier and check your usage statistics in the dashboard. If you're on the free tier, you might have hit the 10,000 requests/month limit.
• 404 Not Found: This generally means the endpoint or resource you are trying to access does not exist. Review the API endpoint URL against the GeoDB API Reference to ensure it is correctly spelled and structured.
• 5xx Server Error: These errors indicate a problem on the GeoDB server side. While less common, if you encounter a 500-level error, it's best to wait a few minutes and retry the request. If the issue persists, check the GeoDB status page or contact their support.
• Incorrect Parameters: Ensure that all required parameters are included in your request and that their values are correctly formatted. For example, if a parameter expects a numeric value, providing a string could cause an error. Consult the parameter definitions in the API documentation.
• Network Issues: Verify your internet connection. Simple network connectivity problems can prevent your request from reaching the API server.
• CORS Issues (Client-Side): If you are making requests directly from a web browser (client-side JavaScript), you might encounter Cross-Origin Resource Sharing (CORS) errors. The GeoDB API is generally configured to handle CORS, but misconfigurations in your web server or browser extensions can sometimes interfere.