Get Hops
This API request returns entities and relations traversed with an N-hop operation.
There is a limit of 1,500 entities that can be returned per API call.
Request
GET {TenantURL}/entities/{entity object URI}/_hops
Parameter | Required | Description | |
---|---|---|---|
Headers |
Authorization
|
Yes | Information about authentication access token in format "Bearer
<accessToken> " (see details in Authentication API). |
Query |
select
|
No | Comma-separated list of properties from the entity structure that
should be returned in a response. Allows you to return a partial object.
This parameter can be used to include the following fields:
The following query returns data for all
fields:
Note: Data
is also returned for all fields if the select
parameter is not used in the request. |
graphTypeURIs
|
No | Comma-separated list of graph types URIs for graphs to be traversed. For more information, see Configuring Graph Types. | |
relationTypeURIs
|
No | Comma-separated list of relation type URIs (see details in Relation Types) for relation to be traversed. | |
entityTypeURIs
|
No | Comma-separated list of entity type URIs (see details in Entity Types) for relation to be traversed. | |
deep
|
No | Limits traversing deep levels. Default is 1 .
|
|
max
|
No | Limits the amount of entities to be returned from the API. If the number of entities does not fit into the specified level, then only entities from previous levels are returned. | |
returnInactive
|
No | Flag to traverse inactive entities/relationships Default is
false . |
|
filterLastLevel |
No |
Flag to NOT count relationships from the last level of deep to the
next level after the last. In a response it affects these entity
parameters: Default is |
|
options
|
No | Comma-separated list of different options which affect entity's JSON
content in the response. Available options:
|
Response
Collections of traversed entities and relations with default details:
- Relations:
uri
: URI of a relation.type
: type of a relation.attributes
: attributes of a relation. It can be displayed or excluded using theselect
parameter.startObject
: contains information about the start object URI, and thedirectionalLabel
object.endObject
: contains information about the end object URI, and thedirectionalLabel
object.startDate
: relation start date, if available.endDate
: relation end date, if available.direction
: direction of a relation, if available.crosswalks
: crosswalks of a relation.consolidatedRating
: consolidated rating of a relation, if available.
- Entities:
uri
: URI of an entity that is traversed.type
: type of an entity.label
: label of an entity. It can be displayed or excluded using theselect
parameter.secondaryLabel
: secondary label of an entity. It can be displayed or excluded using theselect
parameter.attributes
: attributes of an entity. It can be displayed or excluded using theselect
parameter.traversedRelationsCount
: number of relations of an entity that were traversed with this operation.untraversedRelationsCount
: number of relations of an entity that were not traversed with this operation.startDate
: entity start date, if available.endDate
: entity end date, if available.
Consider this graph:
Request 1
GET {TenantURL}/entities/1/_hops?select=entities.attributes.Gender&max=5&deep=1Headers:
Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
Response 1
{
"relations": [{
"URI": "relations/1_2",
"type": "configuration/relationTypes/Parent",
"startObject": {
"objectURI": "entities/1",
"directionalLabel": "mother"
},
"endObject": {
"objectURI": "entities/2",
"directionalLabel": "daughter"
},
"direction": "directed"
}, {
"URI": "relations/1_3",
"type": "configuration/relationTypes/Parent",
"startObject": {
"objectURI": "entities/1",
"directionalLabel": "mother"
},
"endObject": {
"objectURI": "entities/3",
"directionalLabel": "son"
},
"direction": "directed"
}, {
"URI": "relations/2_3",
"type": "configuration/relationTypes/Sibling",
"startObject": {
"objectURI": "entities/2",
"directionalLabel": "sister"
},
"endObject": {
"objectURI": "entities/3",
"directionalLabel": "brother"
},
"direction": "undirected"
}],
"entities": [{
"URI": "entities/1",
"type": "configuration/entityTypes/Individual",
"label": "Ann Roman",
"untraversedRelationsCount": 0,
"traversedRelationsCount": 2,
"attributes": {
"Gender": [{
"value": "Female"
}]
}
}, {
"URI": "entities/2",
"type": "configuration/entityTypes/Individual",
"label": "Marsha Smith",
"untraversedRelationsCount": 0,
"traversedRelationsCount": 2,
"attributes": {
"Gender": [{
"value": "Female"
}]
}
}, {
"URI": "entities/3",
"type": "configuration/entityTypes/Individual",
"label": "John Roman",
"untraversedRelationsCount": 0,
"traversedRelationsCount": 2,
"attributes": {
"Gender": [{
"value": "Male"
}]
}
}]
}
Request 2
GET {TenantURL}/entities/1/_hops?max=2&deep=1Headers: Authorization: Bearer
204938ca-2cf7-44b0-b11a-1b4c59984512
Response 2
{
"relations": [],
"entities": [{
"URI": "entities/1",
"type": "configuration/entityTypes/Individual",
"label": "Ann Roman",
"untraversedRelationsCount": 2,
"traversedRelationsCount": 0
}]
}