Technical

API

Development of a more complete and well-documented Reconciliation API is in progress (see below). We are refining options and adding endpoints in response to community feedback. Our intention is eventually to offer a Swagger interface like the (unrelated!) example here.

In the meantime, the endpoints illustrated here are available for use, but are liable to change without notice.

Reconciliation API

The WHG Reconciliation API provides standardised endpoints for reconciling place names and exploring additional properties of candidate places. It implements portions of the Reconciliation Service API v0.2, a widely-used protocol for data matching on the Web. It is compatible with OpenRefine.

⚠️ Work in progress: This API will require API tokens for authentication. Registered Users will be able to generate a token through their Profile page.

Endpoints, fields, and behaviours are only very partially implemented, and are subject to change.

Endpoints

/reconcile/

• Accepts POST requests with one or more place name queries.

• Returns candidate matches for each query, including:

  • Canonical name

  • Alternative names

  • Match score (normalized 0–100)

  • Exact match flag

• Always returns a top-level GeoJSON FeatureCollection of candidate geometries for visual disambiguation.

• Batch requests are supported, with a configurable limit (batch_size).

• Authentication via API token (Authorization: Bearer <token>) or session/CSRF.

---

Parameter usage

Each query object in the queries payload supports the following parameters:

Parameter	Type	Description
query	string	Free-text search string. Required if no spatial (bounds or lat/lng/radius) or dataset filters are provided.
mode	string	Search mode: "exact" (multi-match), "fuzzy" (“AUTO”, prefix_length=2), "starts" (prefix match), or "in" (substring/wildcard match). Defaults to "fuzzy".
		For a configured fuzzy search, you may instead specify the mode as "prefix_length|fuzziness" (e.g., "2|1"), where prefix_length is the number of initial characters that must match, and fuzziness is "AUTO" or an integer ≤ 2.
fclasses	array	Restrict to specific feature classes (e.g. ["A","L"]). "X" (unknown) is always included automatically.
start	integer	Start year for temporal filtering.
end	integer	End year for temporal filtering (defaults to current year if omitted).
undated	boolean	If true, include results with no temporal metadata in addition to those matching the range.
countries	array	Restrict results to country codes (ISO 2-letter).
bounds	object	GeoJSON geometry collection restricting results spatially (e.g. a bounding polygon).
lat	float	Latitude of the centre for a circular “nearby” search (required together with lng and radius).
lng	float	Longitude of the centre for a circular “nearby” search (required together with lat and radius).
radius	float	Radius in kilometres for a circular “nearby” search (required together with lat and lng).
userareas	array	One or more IDs of user-defined stored areas; geometries are resolved server-side and used as spatial filters.
dataset	integer	Restrict results to a specific dataset ID.
size	integer	Maximum number of results per query (default: 100).

---

Example requests

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"],
        "bounds": {
          "geometries": [{
            "type": "Polygon",
            "coordinates": [[
              [-1.0,51.0],
              [-1.0,52.0],
              [0.5,52.0],
              [0.5,51.0],
              [-1.0,51.0]
            ]]
          }]
        }
      }
    }
  }'

import requests

url = "https://whgazetteer.org/reconcile/"
headers = {"Authorization": "Bearer <API_TOKEN>", "Content-Type": "application/json"}
payload = {"queries": {"q1": {"query": "Glasgow"}}}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

/reconcile/extend/propose

• Accepts POST requests.

• Returns suggested additional properties that clients may request for each candidate:

  • Temporal range (years)

  • Source dataset

  • Country codes

  • Alternative names

/reconcile/extend

• Accepts POST requests with candidate places.

• Computes and returns values for additional properties.

/suggest

• Accepts POST requests to suggest entities or properties.

/preview/

• Accepts POST requests with reconciliation results (JSON payload from /reconcile/).

• Returns rendered HTML showing candidate geometries on a map (Point, LineString, Polygon).

• Supports OpenRefine preview.

• Example:

  curl -X POST https://whgazetteer.org/reconcile/ \
    -H "Content-Type: application/json" \
    -H "Accept: text/html" \
    -H "Authorization: Bearer <token>" \
    -H "User-Agent: notbot" \
    -d '{
         "results": {
           "q1": {
             "result": [
               ...
             ],
             "geojson": {
               "type": "FeatureCollection",
               "features": [
                 {"type":"Feature","properties":{"name":"Test Point"},"geometry":{"type":"Point","coordinates":[0,0]}},
                 {"type":"Feature","properties":{"name":"Test Line"},"geometry":{"type":"LineString","coordinates":[[-10,0],[10,0]]}},
                 {"type":"Feature","properties":{"name":"Test Polygon"},"geometry":{"type":"Polygon","coordinates":[[[-5,-5],[-5,5],[5,5],[5,-5],[-5,-5]]]}}
               ]
             }
           }
         }
       }'
  

Notes

• Geometries are always returned to allow visual disambiguation of candidates.

• This API is compatible with OpenRefine using the Reconciliation Service API protocol.

• The extended reconciliation results use the WHG Place schema, which is available at: https://whgazetteer.org/static/whg_place_schema.jsonld

Code Repositories

The WHG codebase is divided into several GitHub repositories, each with a specific focus:

• WHG PLACE (Place Linkage, Alignment, and Concordance Engine)

This repository contains the Kubernetes server configuration files for deploying and managing the World Historical Gazetteer (WHG) application. It provides a dedicated space for configuring and orchestrating the server environment.

• WHG v3.0b

This repository contains the codebase for the WHG v3.0b application. It is a Django-based web application that provides a user interface for uploading, reconciling, and publishing historical gazetteer data.

• TileBoss

This repository contains the codebase for generation and serving of map tiles for the WHG application. Its functionality will soon be integrated into the WHG PLACE repository.

Issues & Discussions

We welcome feedback, bug reports, and feature requests. Please use the GitHub Issues feature in the appropriate repository. We especially welcome contributions to the current Discussions.