Skip to content

Latest commit

 

History

History
219 lines (173 loc) · 11.2 KB

README.md

File metadata and controls

219 lines (173 loc) · 11.2 KB
Raw

Histograph API

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

Some example queries:

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.