Unify and manage your data

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
Table 1. Parameters
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:
  • entity label (using the label keyword)
  • entity secondaryLabel (using the secondaryLabel keyword)
  • entity or relation attributes (prefixing entities or relations before the attributes keyword)
    Note: The select parameter supports all attributes.
The following query returns data for all fields:
select=label,secondaryLabel,entities.attributes,relations.attributes
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.
activeness_enabledNo

Flag to determine whether to return only active entities and relations.

If set to false, the response includes both active and inactive entities and relations, regardless of their endDate values.

Default is true.

returnInactive No Flag to traverse inactive entities/relationships Default is false.
filterLastLevelNo 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: untraversedRelationsCount and traversedRelationsCount.

Default is true.

returnDataAnywayNo Flag that allows the API to return partial data when used with limitCreditConsumption=true. If the request exceeds the credit consumption limit, the response includes all retrieved data along with the dataComplete=false flag.

Default is false.

options NoComma-separated list of options that affect the structure of entities in the response. Available options:
  • sendHidden: Disabled by default. Includes hidden attributes in the entity JSON if enabled.
  • ovOnly: Returns only attribute values where ov=true.
  • nonOvOnly: Returns only attribute values where ov=false. If a nested or reference attribute has ov=true but contains sub-attributes with ov=false, those sub-attributes won’t appear in the response.
  • sendMasked: Returns masked attribute values if masking is configured in the L2 or L3 configuration.
  • showAppliedSurvivorshipRules: Includes the applied survivorship (OV) rules in a structured format.

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 the select parameter.
    • startObject: contains information about the start object URI, and the directionalLabel object.
    • endObject: contains information about the end object URI, and the directionalLabel 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 the select parameter.
    • secondaryLabel: secondary label of an entity. It can be displayed or excluded using the select parameter.
    • attributes: attributes of an entity. It can be displayed or excluded using the select 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"
			}]
		}
	}],
    "dataComplete": true  
}

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
	}],
    "dataComplete": true
}