Using the API
Development of a more complete and well-documented public API is in progress. We are refining options and adding endpoints in response to community feedback.
This will include 2-way interactions—not only GETs to retrieve selected data, but authorized POSTs to create and populate WHG datasets remotely, for example from annotation platforms.
Comments and suggestions using this form are welcome.
Endpoints
Search union index (whgazetteer.org/api/index?). Returns GeoJSON.
Examples
Sites & settlements named Abydos, in Turkey, Egypt, and Australia.
/api/index/?name=abydos&fclasses=s,p
Feature collection of four attestations for Abydos, EG asserted as matches.
Spatial queries (whgazetteer.org/api/spatial?)
Note that spatial queries can take several seconds to complete.
| parameter | value | notes |
|---|---|---|
| type✳ | string | bbox or nearby (required) |
| sw† | decimal deg. | bbox southwest corner |
| ne† | decimal deg. | bbox northeast corner |
| lon‡ | decimal deg. | longitude (wgs84) |
| lat‡ | decimal deg. | longitude (wgs84) |
| km‡ | integer | buffer distance in km |
| dataset | string | dataset label |
| collection | integer | collection ID |
| fclass | string | 1 or more GeoNames feature class code, comma-separated |
| pagesize | integer | Default is 20; maximum allowed=200 |
✳ always required; † required for bbox; ‡ required for nearby
Examples
Settlements & sites within a bounding box (feature classes 'P' and 'S')
/api/spatial/?type=bbox&sw=31.918,26.186&ne=34.918,28.186fc=P,S
Places in Old World Trade dataset within 100km of given point, ordered
/api/spatial/?type=nearby&lon=31.918&lat=26.186&km=100&dataset=owtrad
Settlements in HGIS de Las Indias dataset within 10km of given point, ordered
/api/spatial/?type=nearby&lon=-103.71&lat=20.66&km=100&dataset=lugares20_redux
Search regions & areas (whgazetteer.org/api/areas?)
| parameter | value | notes |
|---|---|---|
| <none> | n/a | all regions & study areas flagged 'public' |
| id | integer | a single region/area |
| q | string | Search region/area names |
Examples
All regions and public user study areas
http://whgazetteer.org/api/areas
A region by id (the UN "Carribean")
http://whgazetteer.org/api/areas?id=75
Search string
Search datasets (whgazetteer.org/api/datasets)
| parameter | value | notes |
|---|---|---|
| <none> | n/a | metadata for all datasets flagged 'public' |
| id | integer | metadata for a single 'public' dataset |
| label | string | metadata for a single 'public' dataset |
| q | string | string in dataset title or description |
NOTE: All places in a dataset may be downloaded as a file from the owner's dataset portal page, by the dataset owner and collaborators, or if flagged as "public," from the public dataset page.
Examples
List all 'public' datasets
http://whgazetteer.org/api/datasets
A 'public' dataset by id
http://whgazetteer.org/api/datasets?id=1319
A 'public' dataset by label identifier
http://whgazetteer.org/api/datasets?label=rome2
Search title and description for term