Get Neighbors

Lists the neighbors of one or more specified nodes.

The Get Neighbors API returns the neighbors of one or more specified nodes. By default, the API sorts neighbors by their similarity to the specified node.

Quick Start

Queries must specify one or more nodes for which you want to find neighbors. To find out-neighbors for a node (target nodes that the input source node links to), use the source_names or source_ids parameter. To find in-neighbors for a node (source nodes that link to the input target node), use the target_names or target_ids parameter. The following example returns the top five pages that the Wikipedia page 'United States' links to, as ordered by similarity to the "United States" page.

POST /1/api/[async|sync]/getneighbors/v1?source_names=United States&max_results=5

The API returns the neighbors for each node in the query. In the response below, the "nodes" array lists neighbors for the source node "United States".

{
  "neighbors": [
    {
      "source": {
        "id": 521,
        "attributes": {
          "name":"United States"
        }
      },
      "nodes": [
        {
          "id": 43740,
          "sort_value": 0.1122942864894867, 
          "attributes": {
            "name":"Americans"
          }
        },
        {
          "id": 865308,
          "sort_value": 0.08374875038862228,
          "attributes": {
            "name": "Race and ethnicity in the United States"
          }
        },
        {
          "id": 208578,
          "sort_value": 0.08222222328186035,
          "attributes": {
            "name": "Political divisions of the United States"
          }
        }, 
        {
          "id": 4639,
          "sort_value": 0.07894736528396606, 
          "attributes": {
            "name":"California"
          }
        }, 
        {
          "id": 22984, 
          "sort_value": 0.07773109525442123,
          "attributes": {
            "name": "Hispanic and Latino Americans"
          }
        }
      ]
    }
  ]
}

Multiple Input Nodes

It is possible to return neighbors for multiple input nodes. The following query returns a page that "United States" links to , and a page that links to "Germany".

POST /1/api/[async|sync]/getneighbors/v1?source_names=United States&target_names=Germany&max_results=1

When querying with multiple nodes, the suggestions are grouped by input node.

{
  "neighbors": [
    {
      "source": {
        "id": 521,
        "attributes": {
          "name": "United States"
        }
      },
      "nodes": [
        {
          "id": 43740,
          "sort_value": 0.1122942864894867,
          "attributes": {
            "name": "Americans"
          }
        }
      ]
    },
    {
      "target": {
        "id": 1133,
        "attributes": {
          "name": "Germany"
        }
      },
      "nodes": [
        {
          "id": 292665,
          "sort_value": 0.159005269408226,
          "attributes": {
            "name": "History of Germany"
          }
        }
      ]
    }
  ]
}
Synchronous
https://api.havenondemand.com/1/api/sync/getneighbors/v1
Asynchronous
https://api.havenondemand.com/1/api/async/getneighbors/v1
Authentication

This API requires an authentication token to be supplied in the following parameter:

Parameter Description
apikey The API key to use to authenticate the API request.
Parameters

This API accepts the following parameters:

Optional
Name Type Description
graph
enum The graph you want to query. Default value: wiki_eng.
max_results
number The maximum number of results to return. Default value: 6.
sort
enum The sorting method to use for the results. Default value: default.
source_ids
array<number> The IDs of the source nodes that you want to find neighbors for.
source_names
array<string> The names of the source nodes that you want to find neighbors for. You must percent-encode the node names.
target_ids
array<number> The IDs of the target nodes that you want to find neighbors for.
target_names
array<string> The names of the target nodes that you want to find neighbors for. You must percent-encode the node names.
Enumeration Types

This API's parameters use the enumerations described below:

graph
The graph you want to query.
wiki_eng English Wikipedia
Graph where the nodes come from English Wikipedia pages.
sort
The sorting method to use for the results.
default Default
Uses a default sorting algorithm, which sorts nodes by jaccard similarity.
none None
Turn off sorting. You might want to use this option to improve the speed of particularly large queries.

This API returns a JSON response that is described by the model below. This single model is presented both as an easy to read abstract definition and as the formal JSON schema.

Asynchronous Use

Additional requests are required to get the result if this API is invoked asynchronously.

You can use /1/job/status/<job-id> to get the status of the job, including results if the job is finished.

You can also use /1/job/result/<job-id>, which waits until the job has finished and then returns the result.

Model
This is an abstract definition of the response that describes each of the properties that might be returned.
Get Neighbors Response {
neighbors ( array[Neighbors] , optional)
}
Get Neighbors Response:Neighbors {
One of the following: Neighbors_1 or Neighbors_2
nodes ( array[Nodes] )
}
Get Neighbors Response:Neighbors:Nodes {
attributes ( Attributes )
id ( integer ) Node ID.
sort_value ( number , optional) The value of the property used to sort the nodes. The default is jaccard similarity.
}
Get Neighbors Response:Neighbors:Nodes:Attributes {
name ( string ) The name of the node.
}
Neighbors_1 {
source ( Source )
}
Neighbors_1:Source {
id ( integer ) Source node id.
attributes ( Attributes )
}
Neighbors_1:Source:Attributes {
name ( string ) Source node name.
}
Neighbors_2 {
target ( Target )
}
Neighbors_2:Target {
id ( integer ) Target node id.
attributes ( Attributes )
}
Neighbors_2:Target:Attributes {
name ( string ) Target node name.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "neighbors": {
            "items": {
                "oneOf": [
                    {
                        "properties": {
                            "source": {
                                "properties": {
                                    "id": {
                                        "minimum": 0,
                                        "type": "integer"
                                    },
                                    "attributes": {
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "required": [
                                            "name"
                                        ]
                                    }
                                },
                                "required": [
                                    "id",
                                    "attributes"
                                ],
                                "type": "object"
                            }
                        },
                        "required": [
                            "source"
                        ]
                    },
                    {
                        "properties": {
                            "target": {
                                "properties": {
                                    "id": {
                                        "minimum": 0,
                                        "type": "integer"
                                    },
                                    "attributes": {
                                        "properties": {
                                            "name": {
                                                "type": "string"
                                            }
                                        },
                                        "type": "object",
                                        "required": [
                                            "name"
                                        ]
                                    }
                                },
                                "required": [
                                    "id",
                                    "attributes"
                                ],
                                "type": "object"
                            }
                        },
                        "required": [
                            "target"
                        ]
                    }
                ],
                "properties": {
                    "nodes": {
                        "items": {
                            "properties": {
                                "attributes": {
                                    "properties": {
                                        "name": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "name"
                                    ],
                                    "type": "object"
                                },
                                "id": {
                                    "minimum": 0,
                                    "type": "integer"
                                },
                                "sort_value": {
                                    "minimum": 0,
                                    "type": "number"
                                }
                            },
                            "required": [
                                "id",
                                "attributes"
                            ],
                            "type": "object"
                        },
                        "type": "array"
                    }
                },
                "required": [
                    "nodes"
                ],
                "type": "object"
            },
            "type": "array"
        }
    },
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/getneighbors/v1
/api/api-example/1/api/sync/getneighbors/v1
Examples
See this API for yourself - select one of our examples below.
Get Neighbors (inbound)
Retrieve wiki pages linking to 'Europe'
Get Neighbors (outbound)
Retrieve wiki pages linked from 'Europe'
Parameters
Optional
Name Type Value
graph
enum
max_results
number
sort
enum
source_ids
array
Add another value
source_names
array
Add another value
target_ids
array
Add another value
target_names
array
Add another value


ASync – Response An error occurred making the API request
Response Code:
Response Body

	
Making API Request…
Checking result of job

To try this API with your own data and use it in your own applications, you need an API Key. You can create an API Key from your account page - API Keys.

Output Refresh An error occurred making the API request View Input
Rendered RawHtml Response
Result Display
Response Code:
Response Body:

			
Make this call with curl


If you would like to provide us with more information then please use the box below:

We will use your submission to help improve our product.