GeoNames Web Services
May 14,2026

GISBox is a one-stop 3D GIS data editing, conversion and publishing platform that supports editing in multiple GIS formats such as OSGB/GEOTIFF/RVT, converting to 3DTiles/Terrain and publishing.

Introduction

GeoNames Web Services is a suite of RESTful web services that provide programmatic access to the GeoNames geographical database, one of the world's largest free geographic name repositories. Launched in 2006 by Marc Wick, the GeoNames project contains over 11 million unique geographical features and 5.5 million alternate names across approximately 200 languages . The web services offer functionality including full-text search, reverse geocoding (converting coordinates to place names), postal code lookup, and Wikipedia article integration. All data is available under a Creative Commons Attribution license, making it accessible for both free and commercial applications. The services are widely used in mapping applications, logistics tracking, travel planning, and GIS analysis.

File Structure

GeoNames Web Services consist of the following main components:

REST API Endpoint: Base URL is https://api.geonames.org, with all services accessible via HTTP GET requests. JSON, XML, and RDF formats are supported .
Authentication: A registered username must be passed as a query parameter with every request. Free accounts require email confirmation and manual activation of web service access on the account page .
Search Services: Full-text search across place names (search), postal code search (postalCodeSearch), and Wikipedia article search (wikipediaSearch) .
Reverse Geocoding Services: Convert coordinates to country codes (countryCode), administrative subdivisions (countrySubdivision), nearby place names (findNearbyPlaceName), postal codes (findNearbyPostalCodes), or street addresses (US only) .
Place Hierarchy Services: Retrieve administrative children (children), parent hierarchy (hierarchy), siblings, and neighboring places for a given geonameId .
Weather and Earthquakes: Real-time weather observations from METAR stations (weatherJSON) and recent earthquake data (earthquakesJSON) .
Country Information: Return capital, population, area, bounding box, and languages for any country (countryInfo) .
Premium Tier: Paid commercial services offering higher availability (99.9%), faster response times, HTTPS security, email support, and SLA guarantees .

Pros

Massive global coverage: With over 11 million unique features and 5.5 million alternate names in 200+ languages, GeoNames provides one of the most comprehensive free geographic databases available worldwide .
Rich feature classification: Every place is categorized into one of nine feature classes (e.g., P for populated places, H for hydrographic, T for hypsographic) and further subcategorized into 645 feature codes, enabling precise filtering .
Multiple output formats: All services support XML, JSON, and RDF formats. JSON is particularly useful for JavaScript applications, as it avoids cross-domain security restrictions .
Broad language and library support: Official and community-developed client libraries exist for major programming languages including R (geonames package), Python (dltHub integration), PHP (Services_GeoNames), and many others .
Free for most use cases: The basic web services are free with a registered account, making GeoNames accessible for prototyping, academic research, and small-to-medium scale applications. Only high-volume or mission-critical users need the premium tier .
Crowdsourced data quality: Following a Wikipedia-like model, registered users can correct errors and add new place names, allowing the database to improve over time through community contributions .
Integrated Wikipedia content: Specialized web services return Wikipedia articles for nearby places, enabling rich contextual information beyond basic geographic attributes .

Cons

Authentication required for all requests: Unlike many public APIs that allow anonymous low-rate access, GeoNames requires a registered username for every single request, creating friction for initial testing and development .
Rate limiting for free tier: Free accounts have daily and per-second request limits. For production applications with moderate to high volume, upgrading to commercial services is necessary. The exact limits are not publicly documented but are enforced .
No official free SSL endpoint: While premium users get HTTPS (secure.geonames.org), free tier users historically had only HTTP access, though some secure endpoints are now available. This can be a security concern for applications handling user location data .
Variable data quality and completeness: Because GeoNames aggregates data from many sources (national mapping agencies, postal services, user contributions) and relies on crowdsourcing, coverage and accuracy vary significantly by country and region. Remote areas may have poor data .
Coordinate system fixed to WGS84: All coordinates are provided in WGS84, which is suitable for most global applications but cannot be directly used with local datums without transformation .
No guaranteed uptime for free tier: Free services have no service level agreement. The service could change, become unavailable, or be discontinued without notice, making it unsuitable for mission-critical applications without a commercial agreement .
Commercial services require payment: For professional users needing high availability, fast response times, and support, the premium services require payment (via PayPal) with annual credit packages. Pricing is not publicly listed; users must contact sales .
Documentation organization: The official documentation, while comprehensive, is somewhat scattered across multiple pages (web-services.html, JSON-webservices.html, commercial-webservices.html), and some parameters are not consistently documented across all service descriptions.

Application Scenario

GeoNames Web Services are widely used in applications requiring geographic name lookup, reverse geocoding, or postal code resolution. Typical use cases include e-commerce store locators (converting user coordinates to nearby store locations), logistics and delivery tracking (validating addresses and finding nearby postal codes), travel and tourism platforms (providing place descriptions and nearby Wikipedia articles), GIS data enrichment (adding administrative hierarchy information to coordinate datasets), and weather applications (retrieving the closest weather station to a user's location). In academic research, GeoNames serves as a free alternative to commercial geocoding APIs for large-scale geographic analysis. For real estate platforms and online classifieds, the postal code lookup service helps users search listings within specific areas. The service is also commonly integrated into mobile applications for displaying the user's current city or region name when GPS coordinates are available. While free tier is suitable for prototyping and low-volume applications, production systems with higher reliability requirements should consider the premium commercial tier .