Development of the external API is in draft stage. We plan to refine options and add endpoints in response to community feedback. Please use this form for suggestions.
The relational database holds individual records from uploaded datasets
Note that records from all uploaded datasets are assigned a unique identifier within the WHG system (place_id). Both that place_id and the contributor's own src_id will be maintained unless and until the dataset is deleted by its owner. If a dataset is flagged as "public," its records will be accessible via the "database API" as indicated. In this way WHG can serve as a Linked Open Data publisher for those projects unable to stand up their own per-record landing pages.
The "union index": links contributed records deemed to be close or exact matches in the optional accessioning step that follows initial uploading and reconciliation tasks. So, results of an index query will return a set of one or more records as distinct attestations of the "same" place.
Search public database records (whgazetteer.org/api/db?)
| parameter | value | notes |
|---|---|---|
| id | integer | returns single database record |
| name | string | equals or starts with; name, name_contains, or id is required |
| name_contains | string | includes string |
| dataset | string | dataset label |
| fclass | string | 1 or more GeoNames feature class code, comma-separated |
| year | integer | year within attested timespan(s) if any (Note). use '-' for BCE dates, to -9999 |
| ccode | string | 1 or more 2-letter ISO codes , comma separated |
| area | integer | within this region or user study area |
| pagesize | integer | Default is 20; maximum allowed=200 |
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
Abydos, Egypt in the database, attested to exist at 4000 BCE
/api/db/?name=abydos&ccode=eg&year=-4000
Khmer "landscape" features (regions, cultural groups, peoples) or settlements.
Search union index (whgazetteer.org/api/index?). Returns GeoJSON.
Examples
Sites named Abydos: one in Turkey, two in Egypt. Two have two attestations each.
/api/index/?name=abydos&fclass=s
Index record linking the two database records 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=33.918,28.186&fc=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=-98.3067&lat=19.1302&km=10&fc=P&dataset=lugares13k_rel
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
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=1
A 'public' dataset by label identifier
http://whgazetteer.org/api/datasets?label=dplace
Search title and description for term