Документация GeoNames Web Services

GeoNames в основном испольует REST веб-службы.

Важно:

Не используйте 'demo' аккаунт для вашего приложения или ваших тестов. Он предназначен только для образцов ссылок на страницах документации. Создайте свой собственный аккаунт вместо этого.
Параметр 'username' должно быть передано с каждым запросом. Имя пользователя для вашего приложения могут быть зарегистрированы здесь. После этого вы получите электронное письмо с ссылкой для подтверждения и после того, как вы подтвердили электронную почту вы можете включить учетную запись для веб-сервиса на странице вашей учетной записи
Не забудьте параметры URL кодировать строки, содержащие специальные символы или пробелы. (Ветка форума Faq по кодировке URL)
Используйте JSON сервисы если вы хотите использовать GeoNames из JavaScript, поскольку большинство браузеров не позволяют называть XML Services с другого сервера.
Исключения - обработка ошибок

Веб-сервисы

GeoNames search

Веб-сервис для GeoNames полнотекстового поиска в XML и JSON формате. Смотрите описание службы для деталей.

Почтовый индекс Поиск

Url

	»	api.geonames.org/postalCodeSearch?
Результат	»	возвращает список почтовых индексов и мест для топоним / почтовый код запроса в XML-документ Для США первый вернулся почтовый индекс определяется с использованием почтового индекса кода замкнутых фигур, следующие коды почтового индекса основаны на центроид. Для всех других поддерживаемых стран все возвращенные почтовые индексы основаны на центроидов.

Параметр	Значение	Описание
postalcode	Строка (обязательно почтовый индекс или название места)	Почтовый индекс
postalcode_startsWith	строка	первые символы или буквы почтового кода
placename	Строка (обязательно почтовый индекс или название места)	все поля: название места, почтовый индекс, страна, имя администратора (Важно:urlencoded utf8)
placename_startsWith	строка	первые символы названия места
country	строка: код страны, ISO-3166 (опционально)	По умолчанию все страны. Параметр страна может встречаться несколько раз, например: country=FR&country=GP
countryBias	строка	Записи из countryBias перечисленые первыми
maxRows	целое число (опционально)	максимальное количество строк в документе, возвращенного службой. По умолчанию 10
style	строка SHORT,MEDIUM,LONG,FULL (опционально)	многословие возвращаемого XML-документа, по умолчанию = MEDIUM
operator	string AND,OR (optional)	оператор 'AND' выполняет поиск всех терминов в параметре placename, оператор 'OR' ищет любое значение, по умолчанию = AND
charset	string (optional)	по умолчанию 'UTF 8', определяет кодировку, используемую для документа, возвращенного веб-службой.
isReduced	true or false (optional)	по умолчанию 'false',если установлено значение 'true' возвращаются только внешние коды Великобритании. Внимание: значение по умолчанию на коммерческих серверах в настоящее время устанавливается на 'true'. Это будет изменено позже 'false'.
east,west,north,south	float (optional)	ограничивающего параллелепипеда, только функции внутри коробки возвращаются

Пример http://api.geonames.org/postalCodeSearch?postalcode=9011&maxRows=10&username=demo

Эта услуга также доступна в формате JSON:

[more on free-geocoding ...]

Место поиска имен с почтовым индексом (JSON)

Webservice Type : REST /JSON
Url : api.geonames.org/postalCodeLookupJSON?
Параметры: postalcode,country ,maxRows (default = 20),callback, charset (default = UTF-8)
Результат: возвращает список мест для данного почтового кода в формате JSON, отсортированных по почтовому индексу, название места
Пример http://api.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT&username=demo

Детали для этой службы с Ajax шаг за шагом, например, для placename autocomplete

Найти близлежащие почтовые индексы / обратного геокодирования

Эта услуга поставляется в двух вариантах. Вы можете либо передать широту/долготу ( lat/long) почтового кодовое название/место. (postalcode/placename).

Webservice Type : REST
Url : api.geonames.org/findNearbyPostalCodes?
Параметры :
lat,lng, (широта/долгота) radius (радиус (в км)),, maxRows (default = 5),style (verbosity : SHORT,MEDIUM,LONG,FULL), country ((по умолчанию = все страны), localCountry (в приграничных районах этот параметр будет ограничить поиск по локальная страна, значение = true)
или
postalcode (почтовый индекс),country (страна), radius (радиус (в км)), maxRows (default = 5)

Результат: возвращает список почтовых индексов и мест для LAT / LNG запроса в XML-документа. Результат сортируется по расстоянию. Для Канады FSA возвращается (первые 3 символа полного почтового кода)
Пример::
http://api.geonames.org/findNearbyPostalCodes?lat=47&lng=9&username=demo
или
api.geonames.org/findNearbyPostalCodes?postalcode=8775&country=CH&radius=10&username=demo

Этот сервис также доступен в формате JSON:

api.geonames.org/findNearbyPostalCodesJSON?postalcode=8775&country=CH&radius=10&username=demo

[more reverse geocoding webservices]

Postal code country info

Webservice Type : REST
Url : api.geonames.org/postalCodeCountryInfo?
Result : countries for which postal code geocoding is available.
Example : http://api.geonames.org/postalCodeCountryInfo?username=demo

Find nearby populated place / reverse geocoding

Webservice Type : REST
Url : api.geonames.org/findNearbyPlaceName?
Parameters : lat,lng,
lang: language of returned 'name' element (the pseudo language code 'local' will return it in local language),
radius: radius in km (optional), maxRows: max number of rows (default 10)
style: SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
localCountry: in border areas this parameter will restrict the search on the local country, value=true
cities: optional filter parameter with three possible values 'cities1000', 'cities5000','cities15000'. See the download readme for further infos
Result : returns the closest populated place (feature class=P) for the lat/lng query as xml document. The unit of the distance element is 'km'.
Example:
http://api.geonames.org/findNearbyPlaceName?lat=47.3&lng=9&username=demo

This service is also available in JSON format :
http://api.geonames.org/findNearbyPlaceNameJSON?lat=47.3&lng=9&username=demo

Find nearby toponym / reverse geocoding

Webservice Type : REST
Url : api.geonames.org/findNearby?
Parameters : lat,lng, featureClass,featureCode, radius: radius in km (optional), maxRows : max number of rows (default 10)
style : SHORT,MEDIUM,LONG,FULL (default = MEDIUM), verbosity of returned xml document
localCountry: in border areas this parameter will restrict the search on the local country, value=true
Result : returns the closest toponym for the lat/lng query as xml document
Example:
http://api.geonames.org/findNearby?lat=47.3&lng=9&username=demo

This service is also available in JSON format :
http://api.geonames.org/findNearbyJSON?lat=47.3&lng=9&username=demo

Extended Find nearby toponym / reverse geocoding

Webservice Type : REST
Url : api.geonames.org/extendedFindNearby?
Parameters : lat,lng
Result : returns the most detailed information available for the lat/lng query as xml document
It is a combination of several services. Example:
In the US it returns the address information.
In other countries it returns the hierarchy service: http://api.geonames.org/extendedFindNearby?lat=47.3&lng=9&username=demo
On oceans it returns the ocean name.

[more reverse geocoding webservices]

get geoNames feature for geoNameId

Webservice Type : REST
Url : api.geonames.org/get?
Parameters : geonameId, lang (optional), style (optional)
Result : returns the attribute of the geoNames feature with the given geonameId as xml document
Example:
http://api.geonames.org/get?geonameId=1&username=demo.

Place Hierarchy Webservices

Children

Hierarchy

Siblings

Neighbours

Wikipedia Webservices

Find nearby Wikipedia Entries / reverse geocoding

Wikipedia full text search

JSON Webservices

Cities and Placenames

Recent Earthquakes

Weather Stations with most recent Weather Observation

Placename lookup with postalcode

Other Webservices

RSS to GeoRSS Conversion

Details on RSS to GeoRSS converter.

Semantic Web Webservices

Details on GeoNames Semantic Web services.

Country Info (Bounding Box, Capital, Area in square km, Population)

Webservice Type : REST
Url : api.geonames.org/countryInfo?
Parameters : country (default = all countries)
lang : ISO-639-1 language code (en,de,fr,it,es,...) (default = english)
Result : Country information : Capital, Population, Area in square km, Bounding Box of mainland (excluding offshore islands)
Example : http://api.geonames.org/countryInfo?username=demo

An other countryInfo service is available as csv output :
Example : http://api.geonames.org/countryInfoCSV?lang=it&country=DE&username=demo

CountryCode / reverse geocoding

The iso country code of any given point.

Webservice Type : REST
Url : api.geonames.org/countryCode?
Parameters : lat,lng, type, lang, radius (buffer in km for closest country in coastal areas, a positive buffer expands the positiv area whereas a negative buffer reduces it);
Result : returns the iso country code for the given latitude/longitude
With the parameter type=xml this service returns an xml document with iso country code and country name. The optional parameter lang can be used to specify the language the country name should be in. JSON output is produced with type=JSON
Example http://api.geonames.org/countryCode?lat=47.03&lng=10.2&username=demo

[more reverse geocoding webservices]

Country Subdivision / reverse geocoding

The iso country code and the administrative subdivision of any given point.

Webservice Type : REST
Url : api.geonames.org/countrySubdivision?
Parameters : lat,lng, lang (default= names in local language), radius (buffer in km for closest country in coastal areas, a positive buffer expands the positiv area whereas a negative buffer reduces it),level (level of ADM);
Result : returns the country and the administrative subdivison (state, province,...) for the given latitude/longitude
Example http://api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&username=demo

With the parameters 'radius' and 'maxRows' you get the closest subdivisions ordered by distance :
api.geonames.org/countrySubdivision?lat=47.03&lng=10.2&maxRows=10&radius=40

This service is also available in JSON format : api.geonames.org/countrySubdivisionJSON?lat=47.03&lng=10.2&username=demo

Ocean / reverse geocoding

The name of the ocean or sea.

Webservice Type : REST
Url : api.geonames.org/ocean?
Parameters : lat,lng, radius (optional)
Result : returns the ocean or sea for the given latitude/longitude
The oceans returned by the service are listed here. Example http://api.geonames.org/ocean?lat=40.78343&lng=-43.96625&username=demo

This service is also available in JSON format : api.geonames.org/oceanJSON?lat=40.78343&lng=-43.96625&username=demo

Neighbourhood / reverse geocoding

The neighbourhood for US cities. Data provided by Zillow under cc-by-sa license.

Webservice Type : REST
Url : api.geonames.org/neighbourhood?
Parameters : lat,lng
Result : returns the neighbourhood for the given latitude/longitude
Example http://api.geonames.org/neighbourhood?lat=40.78343&lng=-73.96625&username=demo

This service is also available in JSON format : api.geonames.org/neighbourhoodJSON?lat=40.78343&lng=-73.96625&username=demo

[more reverse geocoding webservices]

Elevation - SRTM1

Webservice Type : REST
Url : api.geonames.org/srtm1?
Parameters : lat,lng;
request method: GET or POST
sample area: ca 30m x 30m Result : a single number giving the elevation in meters according to srtm1, ocean areas have been masked as "no data" and have been assigned a value of -32768
Example http://api.geonames.org/srtm1?lat=50.01&lng=10.2&username=demo

This service is also available in XML and JSON format :api.geonames.org/srtm1XML?lat=50.01&lng=10.2&username=demo api.geonames.org/srtm1JSON?lat=50.01&lng=10.2&username=demo

The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000:http://api.geonames.org/srtm1?lats=50.01,51.01&lngs=10.2,11.2&username=demo

Elevation - SRTM3

Shuttle Radar Topography Mission (SRTM) elevation data. SRTM consisted of a specially modified radar system that flew onboard the Space Shuttle Endeavour during an 11-day mission in February of 2000. The dataset covers land areas between 60 degrees north and 56 degrees south.
This web service is using SRTM3 data with data points located every 3-arc-second (approximately 90 meters) on a latitude/longitude grid. Data voids in the original SRTM files have been filled by cgiar. Thanks to Andy Jarvis and Cgiar to allow GeoNames to use the processed data.
Documentation : cgiar-csi,Nasa

The astergdem data has finer resolution, but is not processed. The srtm3v4 data does not have the same resolution as the astergem data, but it is processed. This means holes and data errors have been corrected.

Webservice Type : REST
Url : api.geonames.org/srtm3?
Parameters : lat,lng;
request method: GET or POST
sample area: ca 90m x 90m Result : a single number giving the elevation in meters according to srtm3, ocean areas have been masked as "no data" and have been assigned a value of -32768
Example http://api.geonames.org/srtm3?lat=50.01&lng=10.2&username=demo

This service is also available in XML and JSON format :api.geonames.org/srtm3XML?lat=50.01&lng=10.2&username=demo api.geonames.org/srtm3JSON?lat=50.01&lng=10.2&username=demo

The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000:http://api.geonames.org/srtm3?lats=50.01,51.01&lngs=10.2,11.2&username=demo

Elevation - Aster Global Digital Elevation Model V1 2009

Webservice Type : REST
Url : api.geonames.org/astergdem?
Parameters : lat,lng;
request method: GET or POST
sample are: ca 30m x 30m, between 83N and 65S latitude. Result : a single number giving the elevation in meters according to aster gdem, ocean areas have been masked as "no data" and have been assigned a value of -9999
Example http://api.geonames.org/astergdem?lat=50.01&lng=10.2&username=demo

This service is also available in XML and JSON format : api.geonames.org/astergdemXML?lat=50.01&lng=10.2&username=demo and api.geonames.org/astergdemJSON?lat=50.01&lng=10.2&username=demo

The text version of the service also accepts a list of lat/lng for the parameters 'lats' and 'lngs'. On the free server the number of points per call is limited to 20, for the premium service the limit is 2000. http://api.geonames.org/srtm3?lats=50.01,51.01&lngs=10.2,11.2&username=demo

Elevation - GTOPO30

GTOPO30 is a global digital elevation model (DEM) with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer). GTOPO30 was derived from several raster and vector sources of topographic information. Documentation : USGS Gtopo30

Webservice Type : REST
Url : api.geonames.org/gtopo30?
Parameters : lat,lng;
sample area: ca 1km x 1km Result : a single number giving the elevation in meters according to gtopo30, ocean areas have been masked as "no data" and have been assigned a value of -9999
Example http://api.geonames.org/gtopo30?lat=47.01&lng=10.2&username=demo

This service is also available in JSON format : http://api.geonames.org/gtopo30JSON?lat=47.01&lng=10.2&username=demo

Timezone

Webservice Type : REST
Url : api.geonames.org/timezone?
Parameters : lat,lng, radius (buffer in km for closest timezone in coastal areas),lang (for countryName), date (date for sunrise/sunset);
Result : the timezone at the lat/lng with gmt offset (1. January) and dst offset (1. July)
Example http://api.geonames.org/timezone?lat=47.01&lng=10.2&username=demo

This service is also available in JSON format : http://api.geonames.org/timezoneJSON?lat=47.01&lng=10.2&username=demo

Element:
countryCode: ISO countrycode
countryName: name (language can be set with param lang)
timezoneId: name of the timezone (according to olson), this information is sufficient to work with the timezone and defines DST rules, consult the documentation of your development environment. Many programming environments include functions based on the olson timezoneId (example java TimeZone)
time: the local current time
sunset: sunset local time (date)
sunrise: sunrise local time (date)
rawOffset: the amount of time in hours to add to UTC to get standard time in this time zone. Because this value is not affected by daylight saving time, it is called raw offset.
gmtOffset: offset to GMT at 1. January (deprecated)
dstOffset: offset to GMT at 1. July (deprecated)

оператор