Histograph API

Histograph geocoding and dataset API. A production version of the API is running on https://api.histograph.io.

Some example queries:

• https://api.histograph.io/search?name=utrecht
• https://api.histograph.io/search?uri=http://vocab.getty.edu/tgn/7269983
• https://api.histograph.io/search?name=amsterdam&type=hg:Municipality

To run the API locally, clone this repository and type:

npm install
node index.js

For more information about installing and running the complete Histograph stack, see the histograph/installation repository.

API specification

The Histograph API has five endpoints:

Endpoint	Description
/search	Geocoding and search
/datasets	Datasets, PITs and relations
/ontology	Histograph ontology
/schemas	JSON schemas
/stats	Data and system statistics

Search API

Endpoint	Description
GET /search	Search for place names

Results

Results from the search API are GeoJSON documents (with a JSON-LD context). This means you can easily view the data on a map (with Leaflet, for example). Or just copy and paste API output into geojson.io.

Each Feature represents a Histograph Concept. A Histograph Concept represents a single geospatial concept (i.e. a populated place, a country, a street, etc.), and consists of a set of place-in-time objects (PITs), connected by hg:sameHgConcept relations. For more information about Concepts, PITs and relations, see histograph.io.

Each PIT can have its own name and geometry - you can find a PIT's geometry inside its containing Concept's GeometryCollection, where a PIT's geometryIndex property denoted the index of its geometry in the geometries array. TL;DR:

geojson.features.forEach(function(feature) {

  // Each feature is a Histograph Concept, and consists of a set of PITs
  feature.properties.pits.forEach(function(pit) {

    // A PIT has each own name, dataset and URI or ID.
    // And it's own geometry, too!
    if (pit.geometryIndex > -1) {
      var pitGeometry = feature.geometry.geometries[pit.geometryIndex];
    }
  });
});

Example search API GeoJSON output:

{
  "@context": {
    "…"
  },
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "type": "hg:Street",
        "pits": [
          {
            "@id": "dataset1/12345",
            "name": "Place",
            "type": "hg:Place",
            "dataset": "dataset1",
            "geometryIndex": 0,
            "data": {
              "…"
            },
            "relations": {
              "hg:sameHgConcept": [
                {
                  "@id": "dataset2/54321"
                }
              ],
              "@id": "dataset1/12345"
            }
          }
        ]
      },
      "geometry": {
        "type": "GeometryCollection",
        "geometries": [
          {
            "type": "Point",
            "coordinates": [
              4.48741,
              52.15581
            ]
          }
        ]
      }
    }
  ]
}

Field	Description
@context	JSON-LD context
pits	Array of PITs in Histograph Concept
uri	(External) URI - unique PIT identifier
id	Dataset-internal identifier - unique PIT identifier
@id	Same as either uri or id, used for JSON-LD serialization
name	PIT name
type	PIT type, see the Histograph ontology for a list of accepted types
dataset	Dataset identifier
geometryIndex	Index of PIT's geometry in GeometryCollection's geometries array; -1 if PIT does not have a geometry
data	JSON object containing extra PIT data
relations	Outgoing relations of PIT
hairs	URI and name of each outgoing relation's target PIT
geometry	GeoJSON GeometryCollection containing geometries array with all PIT geometries

Parameters

All Histograph API search calls expect at least one of the following parameters:

Parameter	Example	Description
name	name=Bussum	Elasticsearch query string on PIT names
uri	uri=http://vocab.getty.edu/tgn/7268026	Exact match on uri
id	id=dataset1/123	Exact match on id (dataset internal)
q	q=boskoop	uri query if q's value starts with http, id query if value contains /, name query otherwise, or leave empty q= to query for everything including entities without a name. This can be interesting for example in combination with an intersects.
type	type=hg:Place	Filter on PIT type (or comma-separated list of types). See the Histograph ontology for a list of valid types
dataset	datset=tgn,geonames	Filter on dataset ID (or comma-separated list of IDs)
intersects	intersects=4.9308,52.7126,5.1601,52.5751	Four-coordinate bounding box, GeoJSON string or WKT string specifying the bounding box or polygon PITs have to intersect
before	before=1950
after	after=1910-10-12

Related PITs

Histograph can also search for PITs which have a certain relation (or path or relations) to other PITs. By specifying this relation with the related parameter, one can search for PITs with a hg:liesIn or hg:originatedFrom relation, for example.

Parameter	Example	Description
related	related=hg:liesIn	related must be one (or more, comma-separated) of the relations specified in the Histograph ontology or JSON schema
related.:parameter	related.name=arnhem	Any of the parameters above can be used to filter related PITs

Flags

Parameter	Example	Description
geometry	geometry=false	When set to false, the API will not return GeoJSON geometries. Default is true.
simplify-geometry	simplify-geometry=true	When true, all geometries only the centroid geometries of each concept will be returned. Default is false.

Exact name search

An extra boolean parameter exact is allowed when searching with parameter name, to specify whether to search for exact match (case insensitive) or not. The default value is false.

Example	Description
name=Gorinchem	Search for PIT name, includes results such as Sleeswijk bij Gorinchem
name=Gorinchem&exact=false	Same as above
name=Gorinchem&exact=true	Search for exact PIT names, searches only for PITs exactly named Gorinchem
name=gOrINchEm&exact=true	Same as the previous, as this search is case-insensitive

Datasets API

Endpoint	Data	Description
GET /datasets		All dataset available via Histograph
GET /datasets/:dataset		Metadata of single dataset
GET /datasets/:dataset/pits		All PITs of single dataset
GET /datasets/:dataset/relations		All relations of single dataset
POST /datasets	Dataset	Create new, empty dataset
PATCH /datasets/:dataset	Dataset	Update existing dataset
PUT /datasets/:dataset/pits	PITs	Update all pits of single dataset
PUT /datasets/:dataset/relations	Relations	Update all relations of single dataset
DELETE /datasets/:dataset		Delete a dataset completely

Data

Type	Format	MIME type	JSON schema
Dataset	JSON	application/json	dataset.schema.json
PITs	NDJSON	application/x-ndjson	pits.schema.json
Relations	NDJSON	application/x-ndjson	relations.schema.json

You can send NDJSON data in your PUT request's body when you are uploading a small data set (i.e. less than 5MB). For bigger NDJSON files, you can use multipart/form-data file upload.

Authentication

All POST, PATCH, PUT and DELETE requests require basic authentication via HTTPS.

Ontology API

Endpoint	Description
GET /ontology	Histograph Turtle/N3 RDF ontology, all types and relations

JSON schemas API

Endpoint	Description
GET /schemas/pits	JSON schema for PITs
GET /schemas/relations	JSON schema for relations

Data and system statistics API

Endpoint	Description
GET /stats/queue	Queue length
GET /stats/queries	Results of data statistics queries (executed every n hours)

Copyright (C) 2015 Waag Society.