Search API
API for querying the OntoPop search index.
Please note that the OntoPop backend open-source software project, which includes the event-driven data pipelines and APIs, is undergoing extensive redesign and refactoring as part of OntoPop Community 3.x in order to improve performance, security, extensibility and maintainability. As a result, the documentation on this page will be significantly updated. Please refer to the OntoPop Roadmap for further information.
Note that the OntoPop Search API is under continuous development. OntoPop Community 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.
1. Search Query
The OntoPop Community 2.x Search API simply returns whatever response object is delivered by the underlying search engine. 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
Perform 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 Network Assets that directly impacts"
],
"properties.label": [
"Network Incident"
]
},
"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": [
"Incident causation refers to the factors that are the primary reasons behind an Incident."
]
},
"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 Network Assets that directly impacts"
],
"properties.label": [
"Network Incident"
]
},
"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 Incident resulting in Damage and/or Injury to Vehicles, Persons, or Strategic Road Network 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": [
"Network"
]
},
"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": [
"Network Model"
]
},
"innerHits": {},
"nestedMetaData": null,
"routing": null,
"explanation": null,
"matchedQueries": []
}
...
],
"aggregations": null,
"suggest": null,
"empty": false
}