2. Application Programming Interfaces (APIs)¶

⚠️ Tokens are required for access to most WHG API endpoints (see below).

Full, interactive API documentation is available at https://whgazetteer.org/api/schema/swagger-ui/

The World Historical Gazetteer (WHG) provides two complementary APIs:

2.1. Entity API¶

Access canonical representations of our entities: Places, Datasets, Collections, Areas, and PeriodO Periods.
Retrieve full metadata, names, types, geometries, temporal bounds, authority info, and linked resources.
Machine-readable feature endpoints return valid Linked Places Format (LPF) v1.1 for GIS and reconciliation tools.

2.1.1. Entity Endpoints¶

Endpoint	Method	Description
`/entity/{type}:{id}/`	GET	Human-readable detail page (redirects to web app)
`/entity/{type}:{id}/api`	GET	Machine-readable LPF feature (JSON)
`/entity/{type}:{id}/preview`	GET	HTML preview snippet

Valid entity types: place, dataset, collection, area, period.

2.1.2. Place Identifiers and Source Namespaces¶

Place identifiers include a namespace prefix that indicates the originating source. For example:

place:169687 — a WHG place (no prefix, or equivalently whg)
place:gn:745044 — a GeoNames place
place:tgn:7010731 — a Getty TGN place

All places are returned in Linked Places Format (LPF) v1.1 from the /api endpoint, regardless of source, with a standard structure including @context, type: "Feature", @id, geometry, names, types, links, and when.

You can use the namespaces parameter on Reconciliation and Suggest endpoints to restrict which sources are searched (see Source Namespaces).

Example: Fetching a GeoNames place

curl "https://whgazetteer.org/entity/place:gn:745044/api?token=<token>"

{
  "@context": "https://raw.githubusercontent.com/LinkedPasts/linked-places/master/linkedplaces-context-v1.1.jsonld",
  "type": "Feature",
  "@id": "https://whgazetteer.org/entity/place:gn:745044/api",
  "properties": {
    "title": "İstanbul",
    "ccodes": ["TR"],
    "source_id": "gn:745044"
  },
  "geometry": {
    "type": "Point",
    "coordinates": [28.94966, 41.01384]
  },
  "names": [
    {"toponym": "Constantinople", "lang": "en"},
    {"toponym": "Byzantium", "lang": "en"},
    {"toponym": "İstanbul", "lang": "tr"}
  ],
  "types": [{"identifier": "PPLA", "label": "P", "sourceLabel": "P.PPLA"}],
  "links": [],
  "when": {}
}

Example: Fetching a WHG place

curl "https://whgazetteer.org/entity/place:169687/api?token=<token>"

{
  "@context": "https://raw.githubusercontent.com/LinkedPasts/linked-places/master/linkedplaces-context-v1.1.jsonld",
  "type": "Feature",
  "@id": "https://whgazetteer.org/entity/place:169687/api",
  "properties": {
    "title": "London",
    "ccodes": ["GB"],
    "fclasses": ["P"],
    "dataset": "Getty TGN (partial)",
    "src_id": "7011781"
  },
  "geometry": {"type": "Point", "coordinates": [-0.1275, 51.50722]},
  "names": [{"toponym": "London", "citations": [{"id": "...", "label": "Getty TGN"}]}],
  "types": [{"label": "inhabited places", "identifier": "aat:300008347"}],
  "links": [{"type": "closeMatch", "identifier": "tgn:7011781"}],
  "when": {"timespans": [{"start": {"earliest": "43"}, "end": {"latest": ""}}]}
}

2.1.3. Persistent Identifiers (w3id.org)¶

WHG entities now have permanent identifiers under the https://w3id.org/whg/ namespace. These identifiers resolve via HTTP 303 redirects to the WHG Entity API and are intended to be stable, citable URIs.

Canonical identifier pattern

Base: https://w3id.org/whg/
Entity: https://w3id.org/whg/id/{id} → https://whgazetteer.org/entity/{id}/api (303 redirect)

Content negotiation for the base namespace

If Accept: application/json or application/ld+json, redirect (303) to https://whgazetteer.org/api/schema/.
If Accept: text/html or application/xhtml+xml, redirect (303) to https://whgazetteer.org/.
Otherwise, return HTTP 404.

Examples by entity type

Place (WHG): https://w3id.org/whg/id/place:169687
Place (GeoNames): https://w3id.org/whg/id/place:gn:745044
Dataset: https://w3id.org/whg/id/dataset:1234
Collection: https://w3id.org/whg/id/collection:5678
Area: https://w3id.org/whg/id/area:9012
PeriodO period: https://w3id.org/whg/id/period:3456

Note on DOIs for Published Datasets and Collections

Upon publication, Datasets and Collections are also assigned DOIs. WHG DOIs use the prefix 10.83427 and follow a hyphenated pattern (for example, 10.60681/whg-dataset-1234), which differs from the colon-separated w3id.org identifiers. WHG DOIs are provided through DataCite with support from the University of Pittsburgh Library System.

2.1.4. Namespace Prefix (prefix.cc)¶

The whg: namespace prefix is registered at http://prefix.cc/whg and expands to https://w3id.org/whg/id/. This is useful for compact identifiers in JSON-LD and JSON Schema contexts.

Example usage in a JSON Schema with JSON-LD context

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://w3id.org/whg/schema/place.json",
  "@context": {
    "whg": "https://w3id.org/whg/id/"
  },
  "title": "WHG Place Reference",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "iri",
      "examples": ["whg:place:169687"]
    }
  },
  "required": ["id"]
}

2.2. Reconciliation Service API¶

Compatible with OpenRefine and implements the Reconciliation Service API v0.2.
Supports both Place and PeriodO Period suggestions, batch reconciliation, and property enrichment.
Searches across multiple source indices simultaneously (WHG, GeoNames, Getty TGN, and others).
Results can be filtered by source namespace, country code, GeoNames feature class, and AAT place type.
Data Extension is supported, allowing users to enrich their tables with properties like Geometry, Alternative Names, Temporal Range, and Country Codes after reconciliation.

2.2.1. Reconciliation Endpoints¶

Endpoint	Method	Description
`/reconcile`	GET	Service metadata manifest
`/reconcile`	POST	Batch reconciliation queries or data extension
`/reconcile/properties`	GET	Discover extensible properties
`/suggest/entity`	GET	Typeahead entity suggestions by prefix
`/suggest/property`	GET	Typeahead property suggestions by prefix

2.2.2. Query Parameters¶

The following parameters can be included in each query object within a reconciliation request, or as query-string parameters for the suggest endpoint.

2.2.2.1. Text Search¶

Parameter	Type	Description
`query`	string	Free-text search string. Required.
`mode`	string	Search mode: `exact`, `fuzzy` (default), `starts`, or `in`. Fuzzy mode can also be specified as `prefix_length\|fuzziness` (e.g. `2\|1`).

2.2.2.2. Facet Filtering¶

Parameter	Type	Reconcile	Suggest	Description
`countries`	array or string	✅	✅	ISO 3166-1 alpha-2 country codes. Format: `["US","GB"]` or `"US,GB"`.
`fclasses`	array or string	✅	✅	GeoNames feature classes: `A` (Administrative), `H` (Hydrographic), `L` (Landscape), `P` (Populated places), `R` (Roads/routes), `S` (Sites), `T` (Topographic).
`types`	array or string	✅	✅	AAT place type identifiers (e.g. `"aat:300008347"`). Matched against the `types.identifier` field.
`namespaces`	string	✅	✅	Comma-separated source namespace codes. `whg` = WHG, `gn` = GeoNames, `tgn` = Getty TGN. Omit for all sources.

2.2.2.3. Temporal Filtering¶

Parameter	Type	Description
`start`	integer	Start year for temporal filtering.
`end`	integer	End year (default: current year). Must be ≥ `start`.
`undated`	boolean	Include results with no temporal metadata (default: true).

2.2.2.4. Spatial Filtering¶

Parameter	Type	Description
`bounds`	object	GeoJSON geometry for spatial restriction (see formats below).
`lat`, `lng`, `radius`	float	Circular search: latitude (-90–90), longitude (-180–180), radius in km. All three required together.
`userareas`	array	IDs of user-defined stored areas.

The bounds parameter accepts two formats:

Plain GeoJSON geometry (preferred): {"type": "Polygon", "coordinates": [[[...]]]} — any Polygon or MultiPolygon geometry.
GeometryCollection wrapper: {"geometries": [{"type": "Polygon", "coordinates": [[[...]]]}]} — legacy format, still supported for backward compatibility.

2.2.2.5. Other¶

Parameter	Type	Description
`dataset`	integer	Restrict to a specific dataset ID.
`unlocated`	boolean	Include results with no spatial metadata (default: true).
`limit`	integer	Maximum results per query (default: 100, max: 1000). This is the standard Reconciliation API v0.2 parameter name. `size` is accepted as an alias.

2.2.3. Source Namespaces¶

WHG searches across multiple place indices. Each source is identified by a namespace prefix:

Namespace	Source	ID Example
`whg`	WHG places	`place:169687`
`gn`	GeoNames	`place:gn:745044`
`tgn`	Getty TGN	`place:tgn:7010731`
`wd`	Wikidata	`place:wd:Q84`
`osm`	OpenStreetMap	`place:osm:n123456`
`ohm`	OpenHistoricalMap	`place:ohm:w789012`
`pl`	Pleiades	`place:pl:423025`

Note: The gb namespace (Ordnance Survey) is excluded from results by default to reduce noise. To include it, pass an empty exclude_namespaces list via the gateway API.

When namespaces is omitted, all available sources are searched (except those in the default exclusion list). When specified, only the listed sources are queried — this can improve performance and relevance.

Examples:

"namespaces": "whg" — search only WHG places
"namespaces": "gn,tgn" — search GeoNames and Getty TGN
"namespaces": "whg,gn" — search WHG and GeoNames

2.2.4. Data Extension Properties¶

After reconciliation, you can enrich your data with these properties via the extend endpoint:

Place properties:

Property ID	Description
`whg:names_canonical`	Preferred/canonical place name
`whg:names_summary`	List of all toponyms
`whg:names_array`	Names as structured objects
`whg:countries_codes`	ISO country codes
`whg:countries_objects`	Country objects with code and label
`whg:classes_codes`	GeoNames feature class codes
`whg:classes_objects`	Feature class objects with label and reference
`whg:types_objects`	AAT type objects
`whg:geometry_centroid`	Centroid as “lat, lng” string
`whg:geometry_geojson`	Full GeoJSON geometry
`whg:geometry_wkt`	Geometry as WKT string
`whg:geometry_bbox`	Bounding box
`whg:temporal_objects`	Temporal data as structured objects
`whg:temporal_years`	Temporal range as year values
`whg:dataset`	Source dataset name
`whg:id_short`	WHG entity URI
`whg:id_object`	Entity ID and label as object
`whg:lpf_feature`	Complete LPF feature

Period properties:

Property ID	Description
`whg:chrononym_canonical`	Canonical period label
`whg:chrononym_variants_array`	Variant labels as objects
`whg:chrononym_variants_summary`	Variant labels as strings
`whg:periodo_identifier`	PeriodO identifier
`whg:period_authority_object`	Authority information
`whg:temporal_bounds_objects`	Temporal bounds as objects
`whg:temporal_bounds_years`	Temporal bounds as years
`whg:spatial_coverage_geometry`	Spatial coverage geometry
`whg:spatial_coverage_objects`	Spatial coverage objects

2.2.5. Using the WHG Reconciliation API in OpenRefine¶

The WHG Reconciliation Service allows you to match place names in your spreadsheet data against WHG’s comprehensive collection of historical places. This is particularly useful for disambiguating place names and enriching your data with standardised identifiers, coordinates, and temporal information.

2.2.5.1. Prerequisites¶

Install OpenRefine (version 3.0 or later recommended)
Have a dataset with place name columns that you want to reconcile
Obtain your WHG API token from your Profile page at whgazetteer.org

2.2.5.2. Step 1: Adding the WHG Reconciliation Service¶

Open your project in OpenRefine
Click on the selector button in the column header containing place names, and select Reconcile → Start reconciling…
In the reconciliation dialog, click Add Standard Service (bottom left)
Enter your personalized reconciliation service URL from your WHG Profile page (see below)
Click Add Service

The WHG reconciliation service should now appear in the list of available services.

2.2.5.3. Step 2: Configuring Reconciliation Parameters¶

After selecting the WHG service, you can configure various parameters to improve matching accuracy:

Reconcile each cell to: Select “Place” (the default entity type)
Optional: Also use relevant details from other columns: Check boxes for any columns containing additional context (e.g., country names, dates, coordinates)

2.2.5.4. Step 3: Running Reconciliation¶

Click Start Reconciling
OpenRefine will send your place names to the WHG API in batches
Results will appear in your column with confidence scores
Results may include places from multiple sources (WHG, GeoNames, TGN) — the source namespace is encoded in the entity ID

2.2.5.5. Step 4: Reviewing and Confirming Matches¶

Click on cells showing multiple candidates
Review the suggested matches in the popup dialog
Select the correct match or choose “Create new item” if none match
Use Reconcile → Actions → Match each cell to its best candidate for bulk acceptance (use carefully!)

2.2.5.6. Step 5: Data Extension (Enrichment)¶

After reconciliation, you can add properties from WHG to your dataset:

Click the reconciled column header
Select Edit column → Add columns from reconciled values…
Choose properties to add (see Data Extension Properties for the full list)
Click OK to add the new columns

Note: Data extension works for places from all sources. For some sources, certain properties (e.g. whg:geometry_wkt, whg:temporal_objects) may return empty values if the source data does not include them.

2.2.5.7. Tips for Better Results¶

Pre-process your data: Clean up obvious typos and normalise formatting
Use temporal filters: Historical place names are often ambiguous without temporal context
Leverage additional columns: Include date ranges, broader geographic context, or place types in separate columns and reference them during reconciliation
Filter by namespace: If you know your places are in a specific source (e.g. GeoNames), use namespaces to restrict the search for faster, more relevant results
Filter by country or feature class: Use countries and fclasses to narrow results for common place names
Start with a sample: Test reconciliation on a small subset before processing large datasets
Review auto-matches: Even high-confidence matches should be spot-checked, especially for common place names

2.2.5.8. Batch Reconciliation via API¶

For programmatic access or very large datasets, you can use the WHG Reconciliation API directly. See the full API documentation for details on query structure and response formats.

2.3. API Tokens¶

Registered users can generate an API token from their Profile page. Alongside the token, the Profile page also provides a preconfigured OpenRefine reconciliation service URL, which can be copied and pasted into OpenRefine’s reconciliation dialog, under “Add Standard Service”.

2.3.1. Using an API Token¶

The simplest way to use an API token is to include it as a query parameter in the request URL. For example:

https://whgazetteer.org/reconcile?token=<token>

Otherwise, it may be included in the Authorization header, using the Bearer schema. Requests must also include a suitable User-Agent to avoid bot-filters. For example:

curl -X POST https://whgazetteer.org/reconcile \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "User-Agent: notbot" \
  -d '{
    "queries": {
      "q1": {
        "query": "London",
        "mode": "fuzzy",
        "fclasses": ["A","P"],
        "start": 1200,
        "end": 2050,
        "undated": true,
        "countries": ["GB","US"],
        "namespaces": "whg",
        "bounds": {
          "type": "Polygon",
          "coordinates": [[
            [-1.0,51.0],
            [-1.0,52.0],
            [0.5,52.0],
            [0.5,51.0],
            [-1.0,51.0]
          ]]
        },
        "limit": 5
      }
    }
  }'

2.3.2. Suggest Endpoint Example¶

curl "https://whgazetteer.org/suggest/entity?prefix=Edin&limit=5&countries=GB&fclasses=P&namespaces=whg&token=<token>"

2.3.3. Entity API Example¶

# Fetch a GeoNames place as LPF
curl "https://whgazetteer.org/entity/place:gn:745044/api?token=<token>"

# Fetch a WHG place as LPF
curl "https://whgazetteer.org/entity/place:169687/api?token=<token>"

# Preview HTML snippet for a place
curl "https://whgazetteer.org/entity/place:gn:745044/preview?token=<token>"