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 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

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

parametervaluenotes
idintegerreturns single database record
namestringequals or starts with; name, name_contains, or id is required
name_containsstringincludes string
datasetstringdataset label
fclassstring1 or more GeoNames feature class code, comma-separated
yearintegeryear within attested timespan(s) if any (Note).
use '-' for BCE dates, to -9999
ccodestring1 or more 2-letter ISO codes , comma separated
areaintegerwithin this region or user study area
pagesizeintegerDefault is 20; maximum allowed=200

NOTE: All places in a dataset may be downloaded as a file from the dataset page, by the dataset owner and collaborators.

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.

/api/db/?name_contains=khmer&fclass=p,l

Search union index (whgazetteer.org/api/index?). Returns GeoJSON.

parametervaluenotes
whgidintegerindex identifier; returns 1 or more linked records
namestringexact match; name, name_startswith, or whgid 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 this region 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

Index record linking the two database records for Abydos, EG asserted as matches.

/api/index/?whgid=12608007

Settlements and sites in N. Africa w/part of any name variant starting with "aby."

/api/index/?name_startswith=aby&fclass=p,s&area=85

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

parametervaluenotes
qstringsearch term or place
formatstringanno (default) or geojson

Examples

Search for "empire," returning W3C Web Annotation format

/api/traces/?q=empire

Search for "empire," returning GeoJSON (2 FeatureCollections)

/api/traces/?q=empire&format=geojson

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

parametervaluenotes
<none>n/aall regions & study areas flagged 'public'
idintegera single region/area
qstringSearch 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

http://whgazetteer.org/api/areas?q=africa

Search datasets (whgazetteer.org/api/datasets)

parametervaluenotes
<none>n/ametadata for all datasets flagged 'public'
idintegermetadata for a single 'public' dataset
labelstringmetadata for a single 'public' dataset
qstringstring in dataset title or description

NOTE: All places in a dataset may be downloaded as a file from the dataset page, by the dataset owner and collaborators.

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

http://whgazetteer.org/api/datasets?q=spanish