OntoPop
Search…
Search API
API for querying the OntoPop Search Index.
Last Updated: 01 March 2022 • Page Author: Jillur Quddus
Note that the OntoPop Search API is under continuous development. OntoPop version 2.x provides a basic Search API that is detailed on this page. Based on your OntoPop implementation use-case, you may wish to expose the Search API (either directly or indirectly via a proxy based on the security requirements of your project) of the underlying search service vendor (for example Elasticsearch or Azure Search) which will offer a richer set of features to satisfy your expected query patterns in the event that the OntoPop Search API does not. For further information please refer to the Search API documentation of your deployed search service, for example the Elasticsearch Search API.

Search

The current OntoPop version 2.x Search API simply returns whatever response object is delivered by the underlying search service. Consequently the OntoPop Search API response bodies are deployment-specific and will be different for different search engines integrated with OntoPop (for example Azure Search or Elasticsearch). Thus the response bodies in the examples below (which query an Elasticsearch distributed search index) do NOT represent a standard response schema.

Overview

Execute a free-text search query against the indexed property graph model of an W3C Web Ontology Language (OWL) ontology managed by the OntoPop search index.
HTTP Request Method
POST
API Endpoint
/search/ontologies/{id}

Path Variables

Name
Description
Example
id (integer)
ID of the ontology to query
13

Request Body

Property
Description
Example
query (string) *
Free-text search query (required).
network incident
fields (array)
List of fields to search. If this is not provided, then all fields will be searched by default (optional).
["label", "definition", "description"]
and (boolean)
Whether to use AND boolean logic when a list of fields to search has been provided. If this is set to false or not provided, then OR boolean logic will be used by default. If no list of fields is provided, then this property is ignored completely (optional).
false
exact (boolean)
Whether to use exact matching (enabled by default). If this is set to false, then fuzzy matching will be used. Note that currently fuzzy matching is only used when exactly one field has been provided to search. If no list of fields is provided, or more than one field is provided, then currently exact matching will be used regardless of this property (optional).
true

Headers

Key
Value
Description
Content-Type
application/json
See request body above.
X-API-Key
Issued API Key
See API Authentication for further details.

Responses

HTTP Status
Description
Response Schema
200 OK
Search query successfully executed.
Vendor-specific
401 Unauthorized
Search query request unauthorized.
N/A
500 Internal Server Error
Internal server error.
N/A

Examples

Note that search result highlighting is currently only supported when an explicit list of fields is provided such as in example 2 below.

1. Simple Search Query

Example Request
{
"query": "network incident"
}
Response (HTTP 200 OK)
{
"totalHits": 43,
"totalHitsRelation": "EQUAL_TO",
"maxScore": 10.879223,
"scrollId": null,
"searchHits": [
{
"index": "ontopop83",
"id": "1383522252083",
"score": 10.879223,
"sortValues": [],
"content": {
"vertexId": 1383522252083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/R7TsGnM9Vu625dOJkACw1nS",
"synonym": "Contributory Factor",
"businessArea": "Maintain, Operate, Construct",
"vertexId": 1383522252083,
"latestGitWebhookId": 102,
"ontologyId": 83,
"comment": "Incident causation factors can be described as the factors whose elimination can eliminate hazards or incidents. Multiple factors can cause an incident, including human factors, mechanical factors and environmental factors.",
"definition": "Incident causation refers to the factors that are the primary reasons behind an Incident.",
"vertexKey": "http://webprotege.stanford.edu/R7TsGnM9Vu625dOJkACw1nS_83",
"label": "Causation",
"dataSource": "HSAW STATS19",
"example": "Unsafe Design, Slippery Surfaces"
}
},
"highlightFields": {},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
},
{
"index": "ontopop83",
"id": "2085776916083",
"score": 8.901601,
"sortValues": [],
"content": {
"vertexId": 2085776916083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/RCuUHUwF8sOhovt9F5cgPYA",
"businessArea": "Maintain Operate",
"vertexId": 2085776916083,
"latestGitWebhookId": 102,
"subdomain": "NTIS Confirm CHARM FFC",
"ontologyId": 83,
"comment": "Can either refer to incidents that resulted in or could have resulted in injuries, illnesses, damage to health, or fatalities which may occur at work, office or home.",
"definition": " An unplanned time-bound event that occurs on or near Assets that impacts a Person (or persons) or Assets.",
"vertexKey": "http://webprotege.stanford.edu/RCuUHUwF8sOhovt9F5cgPYA_83",
"label": "Incident",
"type": "Service Incident",
"dataSource": "Confirm CHARM VehicleSensorData TTOC FFC"
}
},
"highlightFields": {},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
}
...
],
"aggregations": null,
"suggest": null,
"empty": false
}

2. Search across explicit fields

Example Request
{
"query": "network incident",
"fields": ["label", "definition", "description"]
}
Response (HTTP 200 OK)
{
"totalHits": 41,
"totalHitsRelation": "EQUAL_TO",
"maxScore": 7.022588,
"scrollId": null,
"searchHits": [
{
"index": "ontopop83",
"id": "980253356083",
"score": 7.022588,
"sortValues": [],
"content": {
"vertexId": 980253356083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/RPNC02PMG2H4xSrrTiebi7",
"businessArea": "Maintain Operate",
"vertexId": 980253356083,
"latestGitWebhookId": 102,
"subdomain": "Confirm",
"ontologyId": 83,
"definition": "An unplanned time-bound event that occurs on or near Strategic Road Network Assets that directly impacts their operation or function.",
"vertexKey": "http://webprotege.stanford.edu/RPNC02PMG2H4xSrrTiebi7_83",
"label": "Network Incident",
"dataSource": "Confirm"
}
},
"highlightFields": {
"properties.definition": [
"An unplanned time-bound event that occurs on or near Strategic Road <em>Network</em> Assets that directly impacts"
],
"properties.label": [
"<em>Network</em> <em>Incident</em>"
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
},
{
"index": "ontopop83",
"id": "1383522252083",
"score": 6.706294,
"sortValues": [],
"content": {
"vertexId": 1383522252083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/R7TsGnM9Vu625dOJkACw1nS",
"synonym": "Contributory Factor",
"businessArea": "Maintain, Operate, Construct",
"vertexId": 1383522252083,
"latestGitWebhookId": 102,
"ontologyId": 83,
"comment": "Incident causation factors can be described as the factors whose elimination can eliminate hazards or incidents. Multiple factors can cause an incident, including human factors, mechanical factors and environmental factors.",
"definition": "Incident causation refers to the factors that are the primary reasons behind an Incident.",
"vertexKey": "http://webprotege.stanford.edu/R7TsGnM9Vu625dOJkACw1nS_83",
"label": "Causation",
"dataSource": "HSAW STATS19",
"example": "Unsafe Design, Slippery Surfaces"
}
},
"highlightFields": {
"properties.definition": [
"<em>Incident</em> causation refers to the factors that are the primary reasons behind an <em>Incident</em>."
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
}
...
],
"aggregations": null,
"suggest": null,
"empty": false
}

3. Search across explicit fields with AND boolean logic

Example Request
{
"query": "network incident",
"fields": ["label", "definition", "description"],
"and": true
}
Response (HTTP 200 OK)
{
"totalHits": 2,
"totalHitsRelation": "EQUAL_TO",
"maxScore": 7.022588,
"scrollId": null,
"searchHits": [
{
"index": "ontopop83",
"id": "980253356083",
"score": 7.022588,
"sortValues": [],
"content": {
"vertexId": 980253356083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/RPNC02PMG2H4xSrrTiebi7",
"businessArea": "Maintain Operate",
"vertexId": 980253356083,
"latestGitWebhookId": 102,
"subdomain": "Confirm",
"ontologyId": 83,
"definition": "An unplanned time-bound event that occurs on or near Strategic Road Network Assets that directly impacts their operation or function.",
"vertexKey": "http://webprotege.stanford.edu/RPNC02PMG2H4xSrrTiebi7_83",
"label": "Network Incident",
"dataSource": "Confirm"
}
},
"highlightFields": {
"properties.definition": [
"An unplanned time-bound event that occurs on or near Strategic Road <em>Network</em> Assets that directly impacts"
],
"properties.label": [
"<em>Network</em> <em>Incident</em>"
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
},
{
"index": "ontopop83",
"id": "1889400313083",
"score": 6.7061954,
"sortValues": [],
"content": {
"vertexId": 1889400313083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/RDC5EKiryOl11nNkRsAOoeJ",
"businessArea": "Operate",
"vertexId": 1889400313083,
"latestGitWebhookId": 102,
"ontologyId": 83,
"definition": "An Incident resulting in Damage and/or Injury to Vehicles, Persons, or Strategic Road Network Assets.",
"vertexKey": "http://webprotege.stanford.edu/RDC5EKiryOl11nNkRsAOoeJ_83",
"label": "Accident",
"dataSource": "STATS19 VehicleSensorData"
}
},
"highlightFields": {
"properties.definition": [
"An <em>Incident</em> resulting in Damage and/or Injury to Vehicles, Persons, or Strategic Road <em>Network</em> Assets."
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
}
],
"aggregations": null,
"suggest": null,
"empty": false
}

4. Fuzzy Matching

Example Request
{
"query": "netwark",
"fields": ["label"],
"exact": false
}
Response (HTTP 200 OK)
{
"totalHits": 5,
"totalHitsRelation": "EQUAL_TO",
"maxScore": 3.8696983,
"scrollId": null,
"searchHits": [
{
"index": "ontopop83",
"id": "1521460135083",
"score": 3.8696983,
"sortValues": [],
"content": {
"vertexId": 1521460135083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/RCGrVyxcVdUB7rI7qGrKvTF",
"businessArea": "Construct Design Operate Plan Maintain",
"vertexId": 1521460135083,
"latestGitWebhookId": 102,
"subdomain": "NTIS",
"ontologyId": 83,
"definition": "The concept of the interconnected set of drivable Assets managed and/or owned by the Licence Holder (Strategic Road Network Assets) represented by a Network Model, with Customers Occupying the assets to perform Journeys.",
"vertexKey": "http://webprotege.stanford.edu/RCGrVyxcVdUB7rI7qGrKvTF_83",
"label": "Network"
}
},
"highlightFields": {
"properties.label": [
"<em>Network</em>"
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
},
{
"index": "ontopop83",
"id": "1844371492083",
"score": 2.9344864,
"sortValues": [],
"content": {
"vertexId": 1844371492083,
"label": "class",
"properties": {
"iri": "http://webprotege.stanford.edu/R8MzvxsWzbT1CeZSELKf1Ku",
"synonym": "Polyline",
"businessArea": "Operate Design Construct Plan Maintain",
"vertexId": 1844371492083,
"latestGitWebhookId": 102,
"subdomain": "NTIS",
"ontologyId": 83,
"definition": "A digital representation of the interconnected set of Assets that, when combined, create and support the physical network or roads (Strategic Road Network Assets) managed by the Licence Holder.",
"vertexKey": "http://webprotege.stanford.edu/R8MzvxsWzbT1CeZSELKf1Ku_83",
"label": "Network Model",
"dataSource": "NEM NTIS STATS19"
}
},
"highlightFields": {
"properties.label": [
"<em>Network</em> Model"
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
}
...
],
"aggregations": null,
"suggest": null,
"empty": false
}