GeoNames Web Services

https://www.geonames.org/export/web-services.html
Admin
GeoNames Web Services is a REST API that provides geographic data services including postal code...
Tokens:9,435
Snippets:30
Trust Score:9.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### GET /countryInfo

Source: https://www.geonames.org/export/web-services.html

Retrieves comprehensive information about countries, including capital, population, area, and bounding box.

```APIDOC
## GET /countryInfo

### Description
Returns country information such as capital, population, area in square km, and mainland bounding box.

### Method
GET

### Endpoint
api.geonames.org/countryInfo

### Parameters
#### Query Parameters
- **country** (string) - Optional - ISO country code (default: all countries)
- **lang** (string) - Optional - ISO-639-1 language code (default: en)
- **username** (string) - Required - Your GeoNames account username

### Response
#### Success Response (200)
- **countryInfo** (object) - Contains capital, population, area, and bounding box data.

### Response Example
{
  "geonames": [
    {
      "countryName": "Germany",
      "capital": "Berlin",
      "population": "82000000",
      "areaInSqKm": "357022"
    }
  ]
}
```

--------------------------------

### GET /countryCode

Source: https://www.geonames.org/export/web-services.html

Performs reverse geocoding to retrieve the ISO country code for a given latitude and longitude.

```APIDOC
## GET /countryCode

### Description
Returns the ISO country code for a specific geographic point.

### Method
GET

### Endpoint
api.geonames.org/countryCode

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude
- **lng** (float) - Required - Longitude
- **type** (string) - Optional - Output format (XML, JSON)
- **lang** (string) - Optional - Language for country name
- **radius** (float) - Optional - Buffer in km for coastal areas

### Response
#### Success Response (200)
- **countryCode** (string) - The ISO country code
- **countryName** (string) - The name of the country

### Response Example
{
  "countryCode": "AT",
  "countryName": "Austria"
}
```

--------------------------------

### Get Elevation Data (SRTM1 - REST API)

Source: https://www.geonames.org/export/web-services.html

Retrieves elevation in meters for a given latitude and longitude using SRTM1 data. Supports GET or POST requests and provides results in XML and JSON formats. Can process multiple points via 'lats' and 'lngs' parameters, with limits on the free server.

```REST
http://api.geonames.org/srtm1?lat=50.01&lng=10.2&username=demo
```

```REST
http://api.geonames.org/srtm1XML?lat=50.01&lng=10.2&username=demo
```

```REST
http://api.geonames.org/srtm1JSON?lat=50.01&lng=10.2&username=demo
```

```REST
http://api.geonames.org/srtm1?lats=50.01,51.01&lngs=10.2,11.2&username=demo
```

--------------------------------

### Get Neighbourhood by Coordinates (REST API)

Source: https://www.geonames.org/export/web-services.html

Finds the neighborhood for US cities based on latitude and longitude. Data is provided by Zillow under a CC-BY-SA license. The service is also available in JSON format.

```REST
http://api.geonames.org/neighbourhood?lat=40.78343&lng=-73.96625&username=demo
```

```REST
http://api.geonames.org/neighbourhoodJSON?lat=40.78343&lng=-73.96625&username=demo
```

--------------------------------

### Get Country Information (REST API)

Source: https://www.geonames.org/export/web-services.html

Retrieves detailed information about countries, including capital, population, area, and bounding box. Supports various languages for country names. The service is accessible via REST API.

```REST
http://api.geonames.org/countryInfo?username=demo
```

```REST
http://api.geonames.org/countryInfoCSV?lang=it&country=DE&username=demo
```

--------------------------------

### Get Ocean Name by Coordinates (REST API)

Source: https://www.geonames.org/export/web-services.html

Identifies the ocean or sea for a given latitude and longitude. The service is available in JSON format and accepts an optional radius parameter.

```REST
http://api.geonames.org/ocean?lat=40.78343&lng=-43.96625&username=demo
```

```REST
http://api.geonames.org/oceanJSON?lat=40.78343&lng=-43.96625&username=demo
```

--------------------------------

### Get Country Subdivision by Coordinates (REST API)

Source: https://www.geonames.org/export/web-services.html

Retrieves the country code and administrative subdivision (state, province) for a given latitude and longitude. Supports JSON output and allows specifying language, radius, and subdivision level. Can return multiple results ordered by distance.

```REST
http://api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&username=demo
```

```REST
http://api.geonames.org/countrySubdivisionJSON?lat=47.03&lng=10.2&username=demo
```

```REST
http://api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&maxRows=10&radius=40&username=demo
```

--------------------------------

### GET /srtm1

Source: https://www.geonames.org/export/web-services.html

Retrieves elevation data in meters for a specific coordinate using SRTM1 data.

```APIDOC
## GET /srtm1

### Description
Returns the elevation in meters for a given latitude and longitude.

### Method
GET

### Endpoint
api.geonames.org/srtm1

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude
- **lng** (float) - Required - Longitude
- **username** (string) - Required - Your GeoNames account username

### Response
#### Success Response (200)
- **srtm1** (integer) - Elevation in meters. Returns -32768 for ocean areas.

### Response Example
{
  "srtm1": 1250
}
```

--------------------------------

### Get Country Code by Coordinates (REST API)

Source: https://www.geonames.org/export/web-services.html

Performs reverse geocoding to find the ISO country code for a given latitude and longitude. Supports XML and JSON output formats, and allows specifying the language for country names. A radius parameter can be used for coastal areas.

```REST
http://api.geonames.org/countryCode?lat=47.03&lng=10.2&username=demo
```

```REST
http://api.geonames.org/countryCode?lat=47.03&lng=10.2&type=JSON&username=demo
```

--------------------------------

### Elevation - Aster Global Digital Elevation Model V2 2011 API

Source: https://www.geonames.org/export/web-services.html

Retrieves elevation data from the Aster Global Digital Elevation Model V2 2011 for a given latitude and longitude. This service provides finer resolution data compared to SRTM3. Supports both GET and POST requests, and can return data in JSON, XML, or text format. It also supports batch requests.

```APIDOC
## GET /astergdem

### Description
Retrieves elevation data from the Aster Global Digital Elevation Model V2 2011. This dataset covers land areas between 83N and 65S latitude with approximately 30m x 30m resolution.

### Method
GET or POST

### Endpoint
`api.geonames.org/astergdem`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude of the location.
- **lng** (float) - Required - Longitude of the location.
- **lats** (list of floats) - Optional - List of latitudes for batch requests.
- **lngs** (list of floats) - Optional - List of longitudes for batch requests.
- **username** (string) - Required - GeoNames username for authentication.
- **type** (string) - Optional - Format of the response (e.g., `json`, `xml`). Defaults to text.

### Request Example
```
http://api.geonames.org/astergdem?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- **elevation** (number) - The elevation in meters. Returns -32768 for ocean areas.

#### Response Example
```json
{
  "elevation": 150
}
```

## GET /astergdemXML

### Description
Retrieves Aster GDEM V2 elevation data in XML format.

### Method
GET

### Endpoint
`api.geonames.org/astergdemXML`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/astergdemXML?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- XML structure containing elevation data.

## GET /astergdemJSON

### Description
Retrieves Aster GDEM V2 elevation data in JSON format.

### Method
GET

### Endpoint
`api.geonames.org/astergdemJSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/astergdemJSON?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- JSON object containing elevation data.

## GET /astergdem (Batch Request)

### Description
Retrieves Aster GDEM V2 elevation data for a list of latitude and longitude pairs.

### Method
GET or POST

### Endpoint
`api.geonames.org/astergdem`

### Parameters
#### Query Parameters
- **lats** (list of floats) - Required - Comma-separated list of latitudes.
- **lngs** (list of floats) - Required - Comma-separated list of longitudes.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/astergdem?lats=50.01,51.01&lngs=10.2,11.2&username=demo
```

### Response
#### Success Response (200)
- A list of elevation values corresponding to the input coordinates.
```

--------------------------------

### Elevation - GTOPO30 API

Source: https://www.geonames.org/export/web-services.html

Retrieves GTOPO30 global digital elevation model data for a given latitude and longitude. This service provides elevation data with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer). Supports GET requests and returns data in JSON or text format.

```APIDOC
## GET /gtopo30

### Description
Retrieves GTOPO30 global digital elevation model (DEM) data. The grid spacing is 30 arc seconds (approximately 1 kilometer).

### Method
GET

### Endpoint
`api.geonames.org/gtopo30`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude of the location.
- **lng** (float) - Required - Longitude of the location.
- **username** (string) - Required - GeoNames username for authentication.
- **type** (string) - Optional - Format of the response (e.g., `json`). Defaults to text.

### Request Example
```
http://api.geonames.org/gtopo30?lat=47.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- **elevation** (number) - The elevation in meters. Returns -9999 for ocean areas.

#### Response Example
```json
{
  "elevation": 500
}
```

## GET /gtopo30JSON

### Description
Retrieves GTOPO30 elevation data in JSON format.

### Method
GET

### Endpoint
`api.geonames.org/gtopo30JSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/gtopo30JSON?lat=47.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- JSON object containing elevation data.
```

--------------------------------

### Get GeoNames Feature by geonameId

Source: https://www.geonames.org/export/web-services.html

Retrieves detailed attributes for a specific GeoNames feature using its unique geonameId. Supports language and style parameters for output customization.

```APIDOC
## GET /get

### Description
Retrieves the attributes of a GeoNames feature identified by its geonameId.

### Method
GET

### Endpoint
`api.geonames.org/get`

### Parameters
#### Query Parameters
- **geonameId** (integer) - Required - The unique identifier for the GeoNames feature.
- **lang** (string) - Optional - Language of the returned name elements.
- **style** (string) - Optional - Verbosity of the output. Options: `SHORT`, `MEDIUM`, `LONG`, `FULL`.
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/get?geonameId=1&username=demo
```

### Response
#### Success Response (200)
Returns an XML document containing the attributes of the specified GeoNames feature.

#### Response Example (XML)
```xml
<geonames>
  <code/>
  <name>Europe</name>
  <alternatenames>
    <alternate>
      <name>Europe</name>
      <lang>en</lang>
    </alternate>
    ...
  </alternatenames>
  <latitude>64.75</latitude>
  <longitude>25.0</longitude>
  <feature>A</feature>
  <contryCode>EU</contryCode>
  <adminCode1></adminCode1>
  <adminCode2></adminCode2>
  <adminName1></adminName1>
  <adminName2></adminName2>
  <population>0</population>
  <elevation>0</elevation>
  <timezone>Europe/Helsinki</timezone>
</geonames>
```
```

--------------------------------

### Elevation - SRTM3 API

Source: https://www.geonames.org/export/web-services.html

Retrieves Shuttle Radar Topography Mission (SRTM3) elevation data for a given latitude and longitude. Supports both GET and POST requests, and can return data in JSON, XML, or text format. It also supports batch requests for multiple points.

```APIDOC
## GET /srtm3

### Description
Retrieves Shuttle Radar Topography Mission (SRTM3) elevation data for a given latitude and longitude. Data voids have been filled, and ocean areas are masked.

### Method
GET or POST

### Endpoint
`api.geonames.org/srtm3`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude of the location.
- **lng** (float) - Required - Longitude of the location.
- **lats** (list of floats) - Optional - List of latitudes for batch requests.
- **lngs** (list of floats) - Optional - List of longitudes for batch requests.
- **username** (string) - Required - GeoNames username for authentication.
- **type** (string) - Optional - Format of the response (e.g., `json`, `xml`). Defaults to text.

### Request Example
```
http://api.geonames.org/srtm3?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- **elevation** (number) - The elevation in meters. Returns -32768 for ocean areas.

#### Response Example
```json
{
  "elevation": 1234
}
```

## GET /srtm3XML

### Description
Retrieves SRTM3 elevation data in XML format.

### Method
GET

### Endpoint
`api.geonames.org/srtm3XML`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/srtm3XML?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- XML structure containing elevation data.

## GET /srtm3JSON

### Description
Retrieves SRTM3 elevation data in JSON format.

### Method
GET

### Endpoint
`api.geonames.org/srtm3JSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/srtm3JSON?lat=50.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- JSON object containing elevation data.

## GET /srtm3 (Batch Request)

### Description
Retrieves SRTM3 elevation data for a list of latitude and longitude pairs.

### Method
GET or POST

### Endpoint
`api.geonames.org/srtm3`

### Parameters
#### Query Parameters
- **lats** (list of floats) - Required - Comma-separated list of latitudes.
- **lngs** (list of floats) - Required - Comma-separated list of longitudes.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/srtm3?lats=50.01,51.01&lngs=10.2,11.2&username=demo
```

### Response
#### Success Response (200)
- A list of elevation values corresponding to the input coordinates.
```

--------------------------------

### Placename Lookup with Postal Code (JSON)

Source: https://www.geonames.org/export/web-services.html

RESTful JSON service to retrieve a list of places for a given postal code. Results are sorted by postal code and placename.

```APIDOC
## GET /postalCodeLookupJSON

### Description
Webservice Type : REST /JSON. Returns a list of places for the given postal code in JSON format, sorted by postal code, placename.

### Method
GET

### Endpoint
api.geonames.org/postalCodeLookupJSON

### Parameters
#### Query Parameters
- **postalcode** (string) - Required - The postal code to look up.
- **country** (string) - Required - The country code (ISO-3166).
- **maxRows** (integer) - Optional - The maximum number of rows to return. Default is 20.
- **callback** (string) - Optional - JSONP callback function name.
- **charset** (string) - Optional - Defines the encoding used for the document returned by the web service. Default is 'UTF-8'.
- **username** (string) - Required - The username for your application.

### Request Example
```
http://api.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT&username=demo
```

### Response
#### Success Response (200)
- **postalCode** (string) - The postal code.
- **name** (string) - The name of the place.
- **countryCode** (string) - The ISO-3166 country code.
- **adminCode1** (string) - The first administrative division code.
- **adminCode2** (string) - The second administrative division code.
- **adminCode3** (string) - The third administrative division code.
- **latitude** (float) - The latitude of the place.
- **longitude** (float) - The longitude of the place.
- **fcl** (string) - Feature class.
- **fcode** (string) - Feature code.
- **toponymName** (string) - The toponym name.
- **population** (integer) - The population of the place.
- **countryName** (string) - The name of the country.
- **adminName1** (string) - The name of the first administrative division.
- **adminName2** (string) - The name of the second administrative division.
- **adminName3** (string) - The name of the third administrative division.

#### Response Example
```json
{
  "postalCodes": [
    {
      "postalCode": "6600",
      "name": "Pfunds",
      "countryCode": "AT",
      "adminCode1": "7",
      "adminCode2": "",
      "adminCode3": "",
      "latitude": 46.81855,
      "longitude": 10.30748,
      "fcl": "P",
      "fcode": "PPL",
      "toponymName": "Pfunds",
      "population": 0,
      "countryName": "Austria",
      "adminName1": "Tyrol",
      "adminName2": "",
      "adminName3": ""
    }
  ]
}
```
```

--------------------------------

### Timezone API

Source: https://www.geonames.org/export/web-services.html

Retrieves timezone information for a given latitude and longitude. Includes GMT offset, DST offset, and local time details. Supports JSON format and accepts optional parameters for radius and language.

```APIDOC
## GET /timezone

### Description
Retrieves the timezone information for a specified latitude and longitude. This includes GMT offset, DST offset, and local time details like current time, sunrise, and sunset.

### Method
GET

### Endpoint
`api.geonames.org/timezone`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude of the location.
- **lng** (float) - Required - Longitude of the location.
- **radius** (integer) - Optional - Buffer in kilometers for determining the closest timezone in coastal areas.
- **lang** (string) - Optional - Language code for `countryName` (e.g., `en`).
- **date** (string) - Optional - Date in `YYYY-MM-DD` format to calculate sunrise/sunset for.
- **username** (string) - Required - GeoNames username for authentication.

### Request Example
```
http://api.geonames.org/timezone?lat=47.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- **countryCode** (string) - ISO country code.
- **countryName** (string) - Name of the country.
- **timezoneId** (string) - Olson timezone ID (e.g., `Europe/Berlin`).
- **time** (string) - Current local time.
- **sunset** (string) - Local sunset time (date).
- **sunrise** (string) - Local sunrise time (date).
- **rawOffset** (number) - Offset to UTC for standard time (in hours).
- **gmtOffset** (number) - Offset to GMT at January 1st (deprecated).
- **dstOffset** (number) - Offset to GMT at July 1st (deprecated).

#### Response Example
```json
{
  "countryCode": "DE",
  "countryName": "Germany",
  "timezoneId": "Europe/Berlin",
  "time": "2023-10-27 10:30:00",
  "sunset": "2023-10-27 17:45:00",
  "sunrise": "2023-10-27 07:15:00",
  "rawOffset": 1,
  "gmtOffset": 1,
  "dstOffset": 2
}
```

## GET /timezoneJSON

### Description
Retrieves timezone information in JSON format.

### Method
GET

### Endpoint
`api.geonames.org/timezoneJSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude.
- **lng** (float) - Required - Longitude.
- **radius** (integer) - Optional - Buffer in kilometers.
- **lang** (string) - Optional - Language code.
- **date** (string) - Optional - Date for sunrise/sunset calculation.
- **username** (string) - Required - GeoNames username.

### Request Example
```
http://api.geonames.org/timezoneJSON?lat=47.01&lng=10.2&username=demo
```

### Response
#### Success Response (200)
- JSON object containing timezone details.
```

--------------------------------

### Find Nearby Populated Place

Source: https://www.geonames.org/export/web-services.html

This service finds the closest populated place (city, town, etc.) to a given latitude and longitude. It supports filtering by language, radius, and number of results.

```APIDOC
## GET /findNearbyPlaceName

### Description
Finds the closest populated place (feature class 'P') for a given latitude and longitude. Supports JSON and XML output.

### Method
GET

### Endpoint
`api.geonames.org/findNearbyPlaceName` or `api.geonames.org/findNearbyPlaceNameJSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude coordinate.
- **lng** (float) - Required - Longitude coordinate.
- **lang** (string) - Optional - Language of the returned 'name' element. Use 'local' for the local language.
- **radius** (integer) - Optional - Search radius in kilometers.
- **maxRows** (integer) - Optional - Maximum number of results to return. Default is 10.
- **style** (string) - Optional - Verbosity of the output. Options: `SHORT`, `MEDIUM`, `LONG`, `FULL`. Default is `MEDIUM`.
- **localCountry** (boolean) - Optional - If true, restricts search to the local country in border areas.
- **cities** (string) - Optional - Filter parameter for city size. Options: `cities1000`, `cities5000`, `cities15000`.
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/findNearbyPlaceName?lat=47.3&lng=9&username=demo
```

### Response
#### Success Response (200)
Returns the closest populated place with details like name, coordinates, and distance.

#### Response Example (XML)
```xml
<geonames>
  <place>
    <name>St. Gallen</name>
    <lat>47.4239</lat>
    <lng>9.37477</lng>
    <distance>18.589</distance>
    <population>74995</population>
    <countryCode>CH</countryCode>
    <adminCode1>26</adminCode1>
    <adminCode2>00000</adminCode2>
    <fcl>A</fcl>
    <fcode>ADM1</fcode>
  </place>
  ...
</geonames>
```
```

--------------------------------

### Find Nearby Postal Codes

Source: https://www.geonames.org/export/web-services.html

This service allows you to find nearby postal codes based on latitude and longitude, or by providing a postal code and country. It supports various parameters to control the search radius, number of results, and verbosity.

```APIDOC
## GET /findNearbyPostalCodes

### Description
Finds nearby postal codes based on latitude/longitude or a given postal code and country. Supports JSON and XML output.

### Method
GET

### Endpoint
`api.geonames.org/findNearbyPostalCodes` or `api.geonames.org/findNearbyPostalCodesJSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required (if postalcode not provided) - Latitude coordinate.
- **lng** (float) - Required (if postalcode not provided) - Longitude coordinate.
- **postalcode** (string) - Required (if lat/lng not provided) - The postal code to search around.
- **country** (string) - Required (if postalcode provided) - The country code (e.g., 'CH' for Switzerland).
- **radius** (integer) - Optional - Search radius in kilometers. Default varies (30km free, 160km premium).
- **maxRows** (integer) - Optional - Maximum number of results to return. Default is 5 (free service), 2500 (premium service).
- **style** (string) - Optional - Verbosity of the output. Options: `_SHORT_`, `_MEDIUM_`, `_LONG_`, `_FULL_`. Default is `_MEDIUM_`.
- **localCountry** (boolean) - Optional - If true, restricts search to the local country in border areas.
- **isReduced** (boolean) - Optional - If true, returns only the first part of the postal code (for GB and NL).
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/findNearbyPostalCodes?lat=47&lng=9&username=demo
```

### Response
#### Success Response (200)
Returns a list of postal codes and places, sorted by distance. For Canada, the FSA (first 3 characters of the postal code) is returned.

#### Response Example (XML)
```xml
<geonames>
  <code type="P">
    <postalcode>6000</postalcode>
    <name>Sargans</name>
    <adminCode1>26</adminCode1>
    <adminCode2>00000</adminCode2>
    <countryCode>CH</countryCode>
    <lat>47.05</lat>
    <lng>9.43333</lng>
    <distance>1.6466</distance>
  </code>
  ...
</geonames>
```
```

--------------------------------

### Postal Code Country Info

Source: https://www.geonames.org/export/web-services.html

Retrieves a list of countries for which postal code geocoding is available. This is a simple endpoint to check service availability.

```APIDOC
## GET /postalCodeCountryInfo

### Description
Returns a list of countries for which postal code geocoding is available.

### Method
GET

### Endpoint
`api.geonames.org/postalCodeCountryInfo`

### Parameters
#### Query Parameters
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/postalCodeCountryInfo?username=demo
```

### Response
#### Success Response (200)
Returns an XML document listing countries with available postal code geocoding.

#### Response Example (XML)
```xml
<geonames>
  <country>
    <code>AD</code>
    <name>Andorra</name>
  </country>
  ...
</geonames>
```
```

--------------------------------

### Postal Code Search API

Source: https://www.geonames.org/export/web-services.html

Webservice for searching postal codes and places based on a query. It supports various parameters to filter results by postal code, placename, country, bounding box, and more. Results can be returned in XML or JSON format.

```APIDOC
## GET /postalCodeSearch

### Description
Webservice for the GeoNames full text search in xml and json format. Returns a list of postal codes and places for the placename/postalcode query as an XML or JSON document.

### Method
GET

### Endpoint
api.geonames.org/postalCodeSearch

### Parameters
#### Query Parameters
- **postalcode** (string) - Required - postal code or placename
- **postalcode_startsWith** (string) - Optional - the first characters or letters of a postal code
- **placename** (string) - Required - all fields : placename, postal code, country, admin name (urlencoded utf8)
- **placename_startsWith** (string) - Optional - the first characters of a place name
- **country** (string) - Optional - country code, ISO-3166. Can occur more than once (e.g., country=FR&country=GP). Default is all countries.
- **countryBias** (string) - Optional - records from the countryBias are listed first
- **maxRows** (integer) - Optional - the maximal number of rows in the document returned by the service. Default is 10
- **style** (string) - Optional - verbosity of returned xml document: _SHORT_, _MEDIUM_, _LONG_, _FULL_. Default = MEDIUM
- **operator** (string) - Optional - the operator 'AND' searches for all terms in the placename parameter, the operator 'OR' searches for any term. Default = AND
- **charset** (string) - Optional - defines the encoding used for the document returned by the web service. Default is 'UTF8'
- **isReduced** (boolean) - Optional - default is 'false'. When set to 'true' only the UK outer codes respectively the NL 4-digits are returned. Attention: the default value on the commercial servers is currently set to 'true'. It will be changed later to 'false'.
- **east,west,north,south** (float) - Optional - bounding box, only features within the box are returned
- **username** (string) - Required - The username for your application.

### Request Example
```
http://api.geonames.org/postalCodeSearch?postalcode=9011&maxRows=10&username=demo
```

### Response
#### Success Response (200)
- **code** (string) - The postal code.
- **name** (string) - The name of the place.
- **countryCode** (string) - The ISO-3166 country code.
- **adminCode1** (string) - The first administrative division code.
- **adminCode2** (string) - The second administrative division code.
- **adminCode3** (string) - The third administrative division code.
- **latitude** (float) - The latitude of the place.
- **longitude** (float) - The longitude of the place.
- **fcl** (string) - Feature class.
- **fcode** (string) - Feature code.
- **toponymName** (string) - The toponym name.
- **population** (integer) - The population of the place.
- **countryName** (string) - The name of the country.
- **adminName1** (string) - The name of the first administrative division.
- **adminName2** (string) - The name of the second administrative division.
- **adminName3** (string) - The name of the third administrative division.

#### Response Example
```json
{
  "postalCodes": [
    {
      "postalCode": "9011",
      "name": "Schenna",
      "countryCode": "AT",
      "adminCode1": "7",
      "adminCode2": "",
      "adminCode3": "",
      "latitude": 46.67518,
      "longitude": 11.19098,
      "fcl": "P",
      "fcode": "PPL",
      "toponymName": "Schenna",
      "population": 0,
      "countryName": "Austria",
      "adminName1": "South Tyrol",
      "adminName2": "",
      "adminName3": ""
    }
  ]
}
```
```

--------------------------------

### Find Nearby Toponym

Source: https://www.geonames.org/export/web-services.html

This service finds the closest toponym (a named place or feature) for a given latitude and longitude. You can filter by feature class and feature code.

```APIDOC
## GET /findNearby

### Description
Finds the closest toponym (named place or feature) for a given latitude and longitude. Supports JSON and XML output.

### Method
GET

### Endpoint
`api.geonames.org/findNearby` or `api.geonames.org/findNearbyJSON`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude coordinate.
- **lng** (float) - Required - Longitude coordinate.
- **featureClass** (string) - Required - The feature class to search for (e.g., 'P' for populated place, 'A' for administrative boundary).
- **featureCode** (string) - Optional - Specific feature code within the feature class. Can be used multiple times or with '!=' for exclusion.
- **radius** (integer) - Optional - Search radius in kilometers.
- **maxRows** (integer) - Optional - Maximum number of results to return. Default is 10.
- **style** (string) - Optional - Verbosity of the output. Options: `SHORT`, `MEDIUM`, `LONG`, `FULL`. Default is `MEDIUM`.
- **localCountry** (boolean) - Optional - If true, restricts search to the local country in border areas.
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/findNearby?lat=47.3&lng=9&featureClass=P&username=demo
```

### Response
#### Success Response (200)
Returns the closest toponym matching the specified criteria.

#### Response Example (XML)
```xml
<geonames>
  <toponym>
    <toponymName>St. Gallen</toponymName>
    <name>St. Gallen</name>
    <lat>47.4239</lat>
    <lng>9.37477</lng>
    <fcl>A</fcl>
    <fcode>ADM1</fcode>
    <population>74995</population>
    <countryCode>CH</countryCode>
    <adminCode1>26</adminCode1>
    <adminCode2>00000</adminCode2>
    <distance>18.589</distance>
  </toponym>
  ...
</geonames>
```
```

--------------------------------

### Extended Find Nearby Toponym

Source: https://www.geonames.org/export/web-services.html

Provides the most detailed geographical information available for a given latitude and longitude. The output varies by region, potentially including address information or ocean names.

```APIDOC
## GET /extendedFindNearby

### Description
Returns the most detailed geographical information available for a given latitude and longitude. The output is context-dependent (e.g., address info in the US, hierarchy elsewhere, ocean names over oceans).

### Method
GET

### Endpoint
`api.geonames.org/extendedFindNearby`

### Parameters
#### Query Parameters
- **lat** (float) - Required - Latitude coordinate.
- **lng** (float) - Required - Longitude coordinate.
- **username** (string) - Required - Your GeoNames username.

### Request Example
```
http://api.geonames.org/extendedFindNearby?lat=47.3&lng=9&username=demo
```

### Response
#### Success Response (200)
Returns detailed geographical information in XML format.

#### Response Example (XML)
```xml
<geonames>
  <place>
    <name>St. Gallen</name>
    <lat>47.4239</lat>
    <lng>9.37477</lng>
    <fcl>A</fcl>
    <fcode>ADM1</fcode>
    <countryCode>CH</countryCode>
    <countryName>Switzerland</countryName>
    <adminCode1>26</adminCode1>
    <adminCode2>00000</adminCode2>
    <adminName1>Sankt Gallen</adminName1>
    <adminName2></adminName2>
    <population>74995</population>
    <timezone>Europe/Zurich</timezone>
  </place>
  ...
</geonames>
```
```
Tokens:
Raw