GeoDB Cities Authentication: API Key Setup & Security (2026)

Authentication overview

GeoDB Cities secures access to its API endpoints primarily through API key authentication. This method requires developers to obtain a unique key from their GeoDB Cities account dashboard and include it with every API request. The API key serves as a credential to identify the calling application and authenticate its access against the GeoDB Cities platform. This approach is common for RESTful APIs providing data access, offering a balance of simplicity and security for managing resource access.

When an API request is made to GeoDB Cities, the system validates the provided API key. If the key is valid and active, the request proceeds, and the requested data is returned. If the key is missing, invalid, or revoked, the API will return an authentication error, preventing unauthorized data access. The GeoDB Cities API is designed as a RESTful service, meaning it uses standard HTTP methods and URL structures for interaction, making API key integration straightforward across various programming languages and environments.

The use of API keys is a widely adopted practice for controlling access to web services. While effective for identification and authorization, it places responsibility on the developer to manage and protect these keys securely to prevent unauthorized use. GeoDB Cities provides documentation on how to properly integrate and manage these keys within applications, ensuring data integrity and preventing misuse of API quotas.

Supported authentication methods

GeoDB Cities primarily supports API key authentication for accessing its various endpoints. This method is suitable for most use cases, including server-side applications, client-side applications with appropriate proxying, and scripts. The API key acts as a secret token, authenticating the user or application making the request.

The following table outlines the supported authentication method for GeoDB Cities:

API keys are typically passed as a query parameter in the URL of each API request. While convenient, this method requires careful handling to prevent keys from being exposed in logs, browser history, or network sniffers if not used over HTTPS. GeoDB Cities mandates the use of HTTPS for all API interactions to encrypt data in transit, mitigating some of these risks. For enhanced security, especially in client-side applications, proxying requests through a secure backend that adds the API key is recommended to keep the key out of public view.

Getting your credentials

To access the GeoDB Cities API, you must first obtain an API key. This key is generated within your GeoDB Cities account and serves as your unique credential for authenticating requests. Follow these steps to get your API key:

1. Sign Up or Log In: Navigate to the GeoDB Cities homepage and either create a new account or log in to an existing one.
2. Access Dashboard: Once logged in, proceed to your account dashboard. This is typically where you manage your subscriptions, view usage statistics, and access developer resources.
3. Locate API Keys Section: Within the dashboard, look for a section dedicated to API keys or developer settings. The exact navigation may vary, but it's usually clearly labeled. Refer to the GeoDB Cities documentation for precise instructions on locating this section.
4. Generate New Key: If you don't have an existing key, you will typically find an option to generate a new API key. Some platforms allow you to name your keys for easier management, especially if you plan to use multiple keys for different applications.
5. Copy Your API Key: Once generated, your API key will be displayed. It is crucial to copy this key immediately and store it securely. For security reasons, GeoDB Cities may only display the full key once, and you might not be able to retrieve it again if lost.
6. Review Usage Limits: Familiarize yourself with the GeoDB Cities pricing and usage policy, including the free tier limits of 10,000 requests per month, to understand how your API key usage will be tracked and billed.

It is recommended to treat your API key as a sensitive secret, similar to a password. Avoid hardcoding it directly into client-side code that is publicly accessible. Instead, use environment variables, secret management services, or a secure backend proxy to protect your key.

Authenticated request example

Once you have obtained your API key, you can use it to make authenticated requests to the GeoDB Cities API. The key is typically passed as a query parameter named apiKey in the request URL. Below is an example using cURL, a common command-line tool for making HTTP requests:

curl "https://wft-api.geodb.com/v0-alpha/cities?limit=5&offset=0&minPopulation=1000000&apiKey=YOUR_API_KEY"

In this example:

• https://wft-api.geodb.com/v0-alpha/cities is the base URL for the GeoDB Cities API endpoint for retrieving city data.
• limit=5 specifies that the response should include a maximum of 5 cities.
• offset=0 indicates the starting point for the results.
• minPopulation=1000000 filters results to cities with a population of at least 1,000,000.
• apiKey=YOUR_API_KEY is where you replace YOUR_API_KEY with the actual API key you obtained from your GeoDB Cities account.

Here's an example in JavaScript, demonstrating how to make an authenticated request using the fetch API:

const API_KEY = 'YOUR_API_KEY'; // Store securely, e.g., in an environment variable
const BASE_URL = 'https://wft-api.geodb.com/v0-alpha';

async function getCities() {
  try {
    const response = await fetch(`${BASE_URL}/cities?limit=5&minPopulation=1000000&apiKey=${API_KEY}`);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error('Error fetching cities:', error);
  }
}

getCities();

These examples illustrate how the API key is integrated into the request URL. For production applications, it is crucial to manage the API key securely, avoiding direct exposure in client-side code or public repositories.

Security best practices

Securing your GeoDB Cities API key is essential to prevent unauthorized access, protect your account's API quota, and maintain the integrity of your applications. Adhering to security best practices can significantly reduce potential risks:

1. Keep API Keys Confidential: Treat your API key as a secret credential. Never embed it directly into client-side code (e.g., JavaScript in a web browser) where it can be easily extracted by users. For web applications, a backend server should make API calls and proxy the data to the client, keeping the API key hidden.
2. Use Environment Variables: When deploying applications, store API keys in environment variables rather than hardcoding them into your source code. This practice prevents the key from being committed to version control systems like Git and makes it easier to manage different keys for development, staging, and production environments. Most cloud providers and CI/CD pipelines support environment variables or secret management services.
3. Implement HTTPS/TLS: Always ensure that all communication with the GeoDB Cities API occurs over HTTPS (Hypertext Transfer Protocol Secure). GeoDB Cities enforces HTTPS, which encrypts data in transit, protecting your API key and other sensitive information from eavesdropping. The IETF RFC 2818 on HTTP Over TLS specifies the requirements for secure communication.
4. Restrict API Key Usage (if applicable): While GeoDB Cities API keys are generally tied to your account for usage tracking, some API providers offer mechanisms to restrict API keys by IP address, HTTP referrer, or specific API endpoints. Although GeoDB Cities primarily uses a single key per account, regularly review their documentation for any updates on key restriction capabilities to minimize the impact of a compromised key.
5. Monitor API Usage: Regularly monitor your API usage through your GeoDB Cities account dashboard. Unexpected spikes in usage could indicate a compromised API key or an issue with your application. Setting up alerts for unusual activity can help you react quickly.
6. Rotate API Keys: Periodically rotate your API keys. This means generating a new key, updating your applications to use the new key, and then revoking the old key. Regular rotation limits the window of exposure for any single key, reducing the impact if a key is compromised.
7. Error Handling: Implement robust error handling in your applications. If an API request fails due to an authentication error, ensure that your application logs the event securely without exposing the API key and handles the error gracefully to prevent service disruption.
8. Secure Development Practices: Follow general secure coding practices, such as input validation and output encoding, to prevent common web vulnerabilities that could inadvertently expose API keys or other sensitive data.

By implementing these best practices, developers can significantly enhance the security posture of their applications integrating with the GeoDB Cities API, protecting both their data and their API quotas.