Using the API

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.

Two place data stores

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 may return one or several records as distinct attestations of the "same" place.

Trace data

We have indexed a limited number of "trace annotation" datasets, which can be searched by keyword. Trace records can optionally be returned in place searches,

Endpoints

NOTE: Only the example links are confirmed to work right now..

Search public database records (whgazetteer.org/api/db?)

parametervaluenotes
idintegerreturns single database record
namestringequals or starts with; name or name_contains is required
name_containsstringincludes string
datasetstringdataset label
ccodestring1 or more 2-letter ISO codes, comma separate
fclassstring1-letter GeoNames feature category ; >=1);
yearintegerattestion timespan includes this year;
use '-' for BCE dates, to -9999
areaintegerwithin this region or user study area

Examples

Two records for Abydos, Egypt in the database, attested to exist at 4000 BCE

http://localhost:8000/api/db?name=abydos&ccode=eg&year=-4000

more to come...

Search union index (whgazetteer.org/api/union?):

parametervaluenotes
idintegerreturns 1 or more linked records
namestringexact match; name or name_startswith is required
name_startswithstringstarts any part of a name
datasetstringdataset label
ccodestring1 or more 2-letter ISO codes, comma separate
fclassstring1-letter GeoNames feature category ; >=1);
yearintegerwithin any timespan of linked records;
use '-' for BCE dates, to -9999
areaintegerwithin thisregion or user study area

Examples

Sites named Abydos: one in Turkey, two in Egypt. Two have two attestations each.

/api/index/?name=abydos&fclass=s

List joining the two db records for Abydos, EG

/api/index/?whgid=12608007

more to come...

Search traces (whgazetteer.org/api/traces?)

parametervaluenotes
qstringsearch term or place

Search areas (whgazetteer.org/api/areas?)

parametervaluenotes
idintegerreturns 1 or more linked records

Search datasets (whgazetteer.org/api/datasets)

parametervaluenotes
idintegerreturns 1 or more linked records