GeoNames Getting Started: API Access & First Request (2026)

Getting started overview

Getting started with GeoNames involves a few key steps to access its extensive database of geographical names and related data. GeoNames offers various web services, including geocoding, reverse geocoding, and elevation data, primarily accessible through RESTful APIs. The process begins with account creation and enabling web service access, followed by constructing API requests using your registered username.

GeoNames is designed to support a wide range of applications, from simple location lookups to more complex geospatial analyses. Its free web services are suitable for many non-commercial and open-source projects, though commercial or high-volume usage may necessitate premium services or data downloads. The API structure generally involves sending HTTP GET requests to specific endpoints with parameters for your query and your GeoNames username for authentication.

This guide will walk you through setting up your GeoNames account, enabling web service access, and making your first API call to retrieve geographical information. Understanding these foundational steps is crucial for integrating GeoNames data into your applications effectively.

Create an account and get keys

To begin using GeoNames web services, you first need to create a free account and enable access to the web services. Unlike many APIs that use API keys or OAuth tokens, GeoNames primarily uses your registered username for authentication in its free web services.

Step 1: Register for a GeoNames account

1. Navigate to the official GeoNames registration page.
2. Fill in the required details, including a desired username, password, and email address.
3. Complete the registration process. You may need to verify your email address.

Step 2: Enable web service access

After successfully registering and logging in, you must explicitly enable web service access for your account. This step is critical as web services are not enabled by default.

1. Log in to your GeoNames account.
2. Once logged in, navigate to your account management page.
3. Look for an option or link titled "Enable Free Web Services" or similar. Click this link to activate access.
4. A confirmation message should appear, indicating that web services are now enabled for your username.

Step 3: Understand rate limits

With a free account, GeoNames imposes specific usage limits. For most free web services, you are allowed up to 30,000 credits per day and 2,000 credits per hour. Understanding these limits is important for designing your application to avoid hitting rate limit errors. Commercial usage or higher volume needs may require considering GeoNames premium web services.

Your first request

After setting up your account and enabling web services, you can make your first API request. We'll use the search service to find information about a specific location, which is a common starting point for geocoding tasks. This example uses the GeoNames search web service, which allows you to query for geographical features by name.

Example: Search for "London"

The search service requires at least one query parameter (e.g., q for query string, name for exact name) and your username. The basic URL structure for the search service is:

http://api.geonames.org/searchJSON?q=query&username=YOUR_USERNAME

Replace YOUR_USERNAME with the username you registered with GeoNames.

Let's find information about "London":

curl "http://api.geonames.org/searchJSON?q=London&maxRows=1&username=YOUR_USERNAME"

This curl command sends an HTTP GET request to the GeoNames searchJSON endpoint. The q=London parameter specifies the search query, and maxRows=1 limits the results to the top match. Remember to replace YOUR_USERNAME with your actual GeoNames username. The searchJSON endpoint returns results in JSON format, which is generally easier to parse programmatically than XML.

A successful response will return a JSON object containing an array of geonames, where each object represents a geographical feature matching your query. For London, you might see something like:

{
  "geonames": [
    {
      "adminCode1": "ENG",
      "lng": "0.12764",
      "geonameId": 2643743,
      "toponymName": "London",
      "countryId": "2635167",
      "fcl": "P",
      "population": 7556900,
      "countryCode": "GB",
      "name": "London",
      "fclName": "city, village,...",
      "countryName": "United Kingdom",
      "lat": "51.50853",
      "fcode": "PPLC"
    }
  ]
}

This response provides detailed information about London, including its coordinates (longitude and latitude), country code, population, and feature class. The geonameId is a unique identifier for the geographical feature, which can be used in other GeoNames services for more specific queries.

Using other services

GeoNames offers a variety of other services. For example, to get elevation data for a specific latitude and longitude:

curl "http://api.geonames.org/astergdemJSON?lat=51.5&lng=0.1&username=YOUR_USERNAME"

This request uses the astergdemJSON service to retrieve the elevation for the provided coordinates. For a complete list of services and their parameters, refer to the GeoNames Web Services Overview.

Common next steps

After successfully making your first request, you can explore various ways to integrate GeoNames into your applications and enhance your geospatial capabilities:

1. Explore other web services: GeoNames offers a comprehensive suite of services beyond basic searching. Investigate services like:

   • Reverse geocoding: Convert coordinates (latitude, longitude) into human-readable addresses or place names using the findNearestAddress or findNearbyPlaceName services.
   • Postal code search: Find postal codes for a given location or retrieve locations within a specific postal code area.
   • Timezone lookup: Determine the timezone for a given set of coordinates.
   • Ocean and population data: Access information about oceans, seas, and population statistics for various geographical areas.

   Detailed documentation for each service is available on the GeoNames web services overview page.

2. Implement error handling: Production applications should always include robust error handling. GeoNames API responses include specific error codes and messages when requests fail, such as invalid parameters or exceeding rate limits. Parse these errors to provide meaningful feedback to users or for debugging purposes.

3. Integrate with a mapping library: To visualize the geographical data obtained from GeoNames, integrate it with a client-side mapping library like Leaflet or OpenLayers. These libraries can render maps, markers, and other geographical features based on the coordinates and information you retrieve from GeoNames.

   For example, to display a marker on a map at the coordinates returned by a GeoNames search, you would typically:

   1. Initialize a map.
   2. Make an API call to GeoNames.
   3. Extract the lat and lng from the response.
   4. Add a marker to your map at those coordinates using the mapping library's functions.

   Many mapping libraries have extensive documentation, such as the Google Maps Platform JavaScript API documentation, which can guide you through the integration process.

4. Consider commercial usage: If your project scales beyond the free tier limits or requires specific commercial licenses, review the GeoNames commercial web services. These services offer higher limits, dedicated support, and additional data options suitable for enterprise applications.

5. Contribute to GeoNames: As a community-driven project, GeoNames allows users to contribute and improve the data. If you notice inaccuracies or missing information, consider contributing to the database to help maintain its quality and comprehensiveness.

Troubleshooting the first call

When making your first API call to GeoNames, you might encounter issues. Here are some common problems and their solutions:

1. "User Account Not Enabled To Use The Free Web Services" error

Problem: This is the most frequent error for new users.

Solution: You haven't enabled web services for your account. Log in to your GeoNames account and look for the "Enable Free Web Services" link. Click it to activate access. This step is mandatory after registration.

2. "Invalid User" or "User Does Not Exist" error

Problem: Your username in the URL is incorrect or misspelled.

Solution: Double-check your username. Ensure it exactly matches the username you registered with GeoNames. Usernames are case-sensitive.

3. "Daily Limit Exceeded" or "Hourly Limit Exceeded" error

Problem: You've made too many requests within an hour or a day.

Solution: The free GeoNames services have limits of 2,000 requests per hour and 30,000 requests per day. Wait for the hourly or daily reset. For higher volumes, consider caching results, implementing rate limiting in your application, or upgrading to GeoNames commercial web services.

4. "Invalid Parameter" or "Missing Parameter" error

Problem: Your request URL is missing a required parameter or contains an incorrectly formatted one.

Solution: Refer to the GeoNames Web Services Overview for the specific service you are using. Ensure all mandatory parameters are present and correctly formatted. For example, the search service typically requires a q or name parameter.

5. No results returned, but no error message

Problem: The API call was successful, but the geonames array in the JSON response is empty.

Solution: This usually means that no geographical features matched your query. Check the spelling of your query terms. Try broadening your search parameters or reducing specificity. For instance, searching for "Londn" might return no results, whereas "London" would.

6. Connection or network issues

Problem: Your client (e.g., curl, browser) cannot connect to the GeoNames API endpoint.

Solution: Verify your internet connection. Check if the GeoNames API server is accessible. You can try pinging api.geonames.org or visiting the GeoNames homepage to ensure the service is online. Firewall or proxy settings might also be blocking the request.

By systematically checking these common issues, you can often diagnose and resolve problems encountered during your initial interactions with the GeoNames API.