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 support Linked Places Format (LPF) for GIS and reconciliation tools.

2.2. Reconciliation Service API

  • Compatible with OpenRefine.

  • Supports both Place and PeriodO suggestions, batch reconciliation, and property enrichment.

  • 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. 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.1.1. Prerequisites

  1. Install OpenRefine (version 3.0 or later recommended)

  2. Have a dataset with place name columns that you want to reconcile

  3. Obtain your WHG API token from your Profile page at whgazetteer.org

2.2.1.2. Step 1: Adding the WHG Reconciliation Service

  1. Open your project in OpenRefine img.png

  2. Click on the selector button in the column header containing place names, and select Reconcile → Start reconciling… img_1.png

  3. In the reconciliation dialog, click Add Standard Service (bottom left)

  4. Enter your personalized reconciliation service URL from your WHG Profile page (see below) img_2.png

  5. Click Add Service

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

2.2.1.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) img_3.png

2.2.1.4. Step 3: Running Reconciliation

  1. Click Start Reconciling

  2. OpenRefine will send your place names to the WHG API in batches

  3. Results will appear in your column with confidence scores

2.2.1.5. Step 4: Reviewing and Confirming Matches

  1. Click on cells showing multiple candidates

  2. Review the suggested matches in the popup dialog img_4.png

  3. Select the correct match or choose “Create new item” if none match

  4. Use Reconcile → Actions → Match each cell to its best candidate for bulk acceptance (use carefully!)

2.2.1.6. Step 5: Data Extension (Enrichment)

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

  1. Click the reconciled column header

  2. Select Edit column → Add columns from reconciled values… img_5.png

  3. Choose properties to add img_6.png

  4. Click OK to add the new columns img_7.png

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

  • 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.1.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”.

img_22.png

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"],
        "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]
            ]]
          }]
        }
      }
    }
  }'