The PeriodO reconciliation API

Describe the reconciliation service
Reconcile period names (using GET)
Reconcile period names (using POST)
Suggest property names
Suggest period definitions
Preview period definition details

Describe the reconciliation service

Fetch a description of the reconciliation service. Returns a JSON object as documented in the service metadata section of the OpenRefine Reconciliation API documentation.

URL path

/
Method

GET
Query parameters

Required

none

Optional

callback=[function name] specify callback function for JSONP requests

Successful response

Status code

200 OK

Body content

{
  "name": "PeriodO reconciliation service",
  "identifierSpace": "https://www.ietf.org/rfc/rfc3986.txt",
  "schemaSpace": "https://www.ietf.org/rfc/rfc3986.txt",
  "defaultTypes": [
    {
      "id": "http://www.w3.org/2004/02/skos/core#Concept",
      "name": "Period definition"
    }
  ],
  "view": {
    "url": "{{id}}"
  },
  "preview": {
    "width": 380,
    "height": 390,
    "url": "http://localhost:8142/preview?id={{id}}"
  },
  "suggest": {
    "property": {
      "service_url": "http://localhost:8142",
      "service_path": "/suggest/properties"
    },
    "entity": {
      "service_url": "http://localhost:8142",
      "service_path": "/suggest/entities",
      "flyout_service_path": "/preview?flyout=true&id=${id}"
    }
  }
}

Sample call
```
curl http://localhost:8142/
```

Reconcile period names (using `GET`)

Given a set of period names (and optionally some other descriptive properties of the named periods), return a ranked list of matching period definitions.

URL path

/
Method

GET
Query parameters

Required

queries=[JSON object literal]

The JSON object literal has arbitrary strings as keys, and as values JSON objects specifying individual queries. Individual queries require
- a query key, the value of which is a string specifying a (partial) period name
and optionally may have:
- a limit key, the value of which is an integer specifying how many results to return (by default all potential matches are returned)
- a properties key, the value of which is an array of JSON object literals, each of which requires:
  - a p key, the value of which matches the id of one of the additional properties supported by the reconciliation service
  - a v key, the value of which is an appropriate value for the additional property
For example, a JSON object specifying three queries:
```
{
  "basic-query": {
    "query": "北宋"
  },
  "limited-query": {
    "query": "bronze age",
    "limit": 1
  },
  "additional-properties-query": {
    "query": "Ранньоримський",
    "properties": [
      {
        "p": "location",
        "v": "Ukraine"
      },
      {
        "p": "start",
        "v": "200"
      },
      {
        "p": "stop",
        "v": "600"
      }
    ]
  }
}
```
Optional

callback=[function name] specify callback function for JSONP requests

Successful response

Status code

200 OK

Body content

A successful request will return a JSON object with keys corresponding to the ones provided in the queries object. Each value is a JSON object with a single result key, the value of which is an array of JSON result objects. Each result object describes a single period definition and has the following keys:

id is the permanent identifier URL of the period definition
name is a descriptive label for the period definition
type asserts that the period definition is a skos:Concept
score can be used for ranking matches by "closeness," lower numbers indicate closer matches
match will be true if and only if there was just a single match

For example, a successful response to the queries above:

{
  "basic-query": {
    "result": [
      {
        "id": "http://n2t.net/ark:/99152/p0fp7wvjvn8",
        "name": "Northern Song [China, China: 0960 to 1127]",
        "type": [
          {
            "id": "http://www.w3.org/2004/02/skos/core#Concept",
            "name": "Period definition"
          }
        ],
        "score": 0,
        "match": true
      }
    ]
  },
  "limited-query": {
    "result": [
      {
        "id": "http://n2t.net/ark:/99152/p0z3skmnss7",
        "name": "Bronze [Palestine, Israel, Jordan: -3299 to -1199]",
        "type": [
          {
            "id": "http://www.w3.org/2004/02/skos/core#Concept",
            "name": "Period definition"
          }
        ],
        "score": 0,
        "match": false
      }
    ]
  },
  "additional-properties-query": {
    "result": [
      {
        "id": "http://n2t.net/ark:/99152/p06v8w4dbcf",
        "name": "Ранньоримський період [Ukraine, Ukraine: -0049 to 0175]",
        "type": [
          {
            "id": "http://www.w3.org/2004/02/skos/core#Concept",
            "name": "Period definition"
          }
        ],
        "score": 0,
        "match": true
      }
    ]
  }
}

Error response
- Status code
  
  400 Bad Request
  
  Body content
  
  A 400 error indicates that the value of queries could not be parsed:
  
  malformed queries

Sample call

curl http://localhost:8142/ \
    --get \
    --data-urlencode 'queries={"basic-query":{"query":"北宋"},"limited-query":{"query":"bronze age","limit":1},"additional-properties-query":{"query":"Ранньоримський","properties":[{"p":"location","v":"Ukraine"},{"p":"start","v":"-0050"},{"p":"stop","v":"0175"}]}}'

Reconcile period names (using `POST`)

If you are reconciling a large number of period names at once, you may need to send a POST request rather than a GET request.

URL path

/
Method

POST
Data

Required

queries=[JSON object literal]

The form of the JSON object literal is as specified above for a GET request.

Optional

callback=[function name] specify callback function for JSONP requests
Success Response
- Code
  
  200 OK
  
  Content
  
  Same as for a successful GET request.
Error Response
- Code
  
  400 Bad Request
  
  Content
  
  A 400 error indicates that the value of queries could not be parsed:
  
  malformed queries

Sample Call:

curl http://localhost:8142/ \
    --data-urlencode 'queries={"basic-query":{"query":"北宋"},"limited-query":{"query":"bronze age","limit":1},"additional-properties-query":{"query":"Ранньоримський","properties":[{"p":"location","v":"Ukraine"},{"p":"start","v":"-0050"},{"p":"stop","v":"0175"}]}}'

Suggest property names

Fetch a list of names of additional properties (such as location) that can be specified when reconciling period names.

URL path

/suggest/properties
Method

GET
Query parameters

Required

none

Optional

callback=[function name] specify callback function for JSONP requests

Successful response

Status code

200 OK

Body content

{
  "code": "/api/status/ok",
  "status": "200 OK",
  "result": [
    {
      "id": "location",
      "name": "Spatial coverage"
    },
    {
      "id": "start",
      "name": "Year or start year"
    },
    {
      "id": "stop",
      "name": "End year"
    }
  ]
}

Sample call

curl http://localhost:8142/suggest/properties

Suggest period definitions

Given a specified sequence of characters, fetch a list of period definitions with labels containing that sequence. Intended to be used for auto-suggesting input fields.

URL path

/suggest/entities
Method

GET
Query parameters

Required

prefix=[character sequence]

Optional

callback=[function name] specify callback function for JSONP requests

Successful response

Status code

200 OK

Body content

{
  "code": "/api/status/ok",
  "status": "200 OK",
  "result": [
    {
      "id": "http://n2t.net/ark:/99152/p06v8w4nfqg",
      "name": "Bashkëkohore [Albania, Albania: 1944 to 2000]",
      "type": [
        {
          "id": "http://www.w3.org/2004/02/skos/core#Concept",
          "name": "Period definition"
        }
      ],
      "score": 0,
      "match": false
    },
    {
      "id": "http://n2t.net/ark:/99152/p0qhb662s6j",
      "name": "Bashkëkohore [Albania, Albania: 1944 to 2000]",
      "type": [
        {
          "id": "http://www.w3.org/2004/02/skos/core#Concept",
          "name": "Period definition"
        }
      ],
      "score": 0,
      "match": false
    }
  ]
}

Sample call

curl http://localhost:8142/suggest/entities?prefix=bashkekohore

Preview period definition details

URL path

/preview
Method

GET
Query parameters

Required

id=[period definition identifier]

Optional

flyout=true send HTML as the value of a JSON object with a single html property

callback=[function name] specify callback function for JSONP requests

Successful response

Status code

200 OK

Body content

<!doctype html>
<html>
<body bgcolor="white">
<style>
  dl {
    font-family: sans-serif;
    font-size: 13px !important;
    margin: 0.5em !important;
  }
  dh { color: #93a1a1 }
  dd {
    margin-bottom: 1em !important;
    margin-left: 1em !important;
  }
  p { margin: 0.5em 0; font-size: 13px !important; }
  a { color: #4272db; text-decoration: none }
</style>
<dl>
  <dh>Period</dh>
  <dd>
    <p><a target="_blank" href="http://n2t.net/ark:/99152/p0fp7wvjvn8">Northern Song</a></p>
    <p><i>北宋, Beisong, 北宋</i></p>
  </dd>

  <dh>Source</dh>
  <dd>
    <p>
      <a target="_blank"
         href="http://n2t.net/ark:/99152/p0fp7wv">Merrick Lex Berman. CHGIS: Major Chinese Periods Chronology. 2015.</a>
    </p>
    <p>
      <i>contains 52 period definitions</i>
    </p>
  </dd>

  <dh>Earliest start</dh>
  <dd>
    <p>960</p>
    <p><i>ISO year 960</i></p>
  </dd>

  <dh>Latest stop</dh>
  <dd>
    <p>1127</p>
    <p><i>ISO year 1127</i></p>
  </dd>

  <dh>Spatial coverage</dh>
  <dd>
    <p>China</p>
    <p><i>China</i></p>
    </p>
  </dd>
</dl>

Error Response
- Code
  
  404 Not Found
  
  Content
  
  A 404 error indicates that the value of id does not identify a period definition:
  
  'foo' is not a period definition URI

Sample Call:

curl http://localhost:8142/preview?id=http://n2t.net/ark:/99152/p0fp7wvjvn8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API.md

API.md

The PeriodO reconciliation API

Describe the reconciliation service

Reconcile period names (using `GET`)

Reconcile period names (using `POST`)

Suggest property names

Suggest period definitions

Preview period definition details

Files

API.md

Latest commit

History

API.md

File metadata and controls

The PeriodO reconciliation API

Describe the reconciliation service

Reconcile period names (using GET)

Reconcile period names (using POST)

Suggest property names

Suggest period definitions

Preview period definition details

Reconcile period names (using `GET`)

Reconcile period names (using `POST`)