Using Custom Gazetteer APIs

The Geotagging Widget needs a configured gazetteer API endpoint to support place search. There are two built-in API connectors:

• one that queries OpenStreetMap, using the public version of their Nominatim API
• one that queries the World Historical Gazetteer Places union index

You can configure which built-in gazetteer service to use via the search config option:

var config = {
  // ... other config options

  // Possible values for built-in endpoints are 'osm' or 'whg'
  search: 'osm'
};

var anno = Annotorious.init({
  image: 'hallstatt',
  widgets: [
    { widget: recogito.GeoTagging(config) },
    'COMMENT'
  ]
});

Configuring your own gazetteer connector

Instead of osm or whg, you can also provide a JavaScript function to connect other gazetteer APIs. The function must:

• take a string as input (= the search query=
• return as response a Promise of a single object that represents the top-most search result for the query

The format of the response object must be as follows:

{
  lat: 48.2,
  lng: 16.37,
  geometry: {
    type: 'Point',
    coordinates: [ 16.37, 48.2 ]
  },
  uri: 'https://sws.geonames.org/2761369'
}

Field details:

• lat: latitude of a representative point (e.g. centroid)
• lng: longitude of a representative point (e.g. centroid)
• geometry: GeoJSON geometry (supports all GeoJSON geometry types)
• uri: gazetteer URI (optional!)

Using your custom function

To use a custom function, simply supply it as an argument to the search property in the config.

var MyGazetteerConnector = function(query) {
  return fetch('https://www.example.com/my-gazetteer?q=' + query).then(function(res) {
    return res.json();
  }).then(function(data) {
    // Crosswalk to the format expected by the widget -
    // this part depends on the schema of your API!
    return {
      lat: data[0].latitude,
      lng: data[0].longitude,
      geometry: {
        type: 'Point',
        coordinates: [ data[0].longitude, data[0].latitude ]
      }
    }
  });
}

var anno = Annotorious.init({
  image: 'hallstatt',
  widgets: [
    { widget: recogito.GeoTagging({ search: MyGazetteerConnector }) },
  ]
});