Get Common Neighbors

Finds the common neighbors of the nodes that you specify.

The Get Common Neighbors API finds the common neighbors of the nodes that you specify.

Quick Start

Queries must specify one or more nodes for which you want to find common 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 five pages that are linked to from at least one of the pages United Kingdom, France, or Italy.

POST /1/api/[async|sync]/getcommonneighbors/v1?source_names=United Kingdom,France,Italy&max_results=5

The API returns all the neighbors of the nodes you specify, together with a commonality value that indicates how many of your input nodes the neighbor shares. For example, a commonality value of three shows that the listed node is a neighbor of three of your input nodes. The results return in commonality order (highest to lowest).

{
  "nodes": [
    {
      "id": 1696429,
      "sort_value": 3,
      "commonality": 3,
      "attributes": {
        "name": "List of countries by military expenditures"
      }
    },
    {
      "id": 1280570,
      "sort_value": 3,
      "commonality": 3,
      "attributes": {
        "name": "List of countries by GDP (PPP)"
      }
    },
    {
      "id": 875548,
      "sort_value": 3,
      "commonality": 3,
      "attributes": {
        "name": "List of countries by GDP (nominal)"
      }
    },
    {
      "id": 541115,
      "sort_value": 3,
      "commonality": 3,
      "attributes": {
        "name": "Purchasing power parity"
      }
    },
    {
      "id": 380688,
      "sort_value": 3,
      "commonality": 3,
      "attributes": {
        "name": "Developed country"
      }
    }
  ]
}

To return nodes that are common to all of your input nodes, you can set the min_commonality parameter to be the number of input nodes in your query.

Specifying Source and Target Nodes

It is possible to specify both source and target nodes in the same query. For example, the following query returns pages that are linked from "United Kingdom" and link to "France".

POST /1/api/[async|sync]/getcommonneighbors/v1?source_names=United Kingdom&target_names=France&min_commonality=2

Synchronous
https://api.havenondemand.com/1/api/sync/getcommonneighbors/v1
Asynchronous
https://api.havenondemand.com/1/api/async/getcommonneighbors/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.
min_commonality
number The minimum commonality that the results must have. Default value: 2.
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 source nodes that you want to find neighbors for.
target_names
array<string> The names of the source 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

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 Common Neighbors Response {
nodes ( array[Nodes] , optional)
}
Get Common Neighbors Response:Nodes {
attributes ( Attributes , optional)
id ( integer , optional) Node ID
commonality ( integer , optional) The number of source or target nodes connected to each result.
sort_value ( integer , optional) The value of the property used to sort the nodes. The default is commonality.
}
Get Common Neighbors Response:Nodes:Attributes {
name ( string ) The name of the node.
}
Model Schema
This is a JSON schema that describes the syntax of the response. See json-schema.org for a complete reference.
{
    "properties": {
        "nodes": {
            "items": {
                "properties": {
                    "attributes": {
                        "properties": {
                            "name": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "name"
                        ],
                        "type": "object"
                    },
                    "id": {
                        "type": "integer"
                    },
                    "commonality": {
                        "type": "integer"
                    },
                    "sort_value": {
                        "type": "integer"
                    }
                },
                "type": "object"
            },
            "type": "array"
        }
    },
    "type": "object"
}
https://api.havenondemand.com/1/api/sync/getcommonneighbors/v1
/api/api-example/1/api/sync/getcommonneighbors/v1
Examples
See this API for yourself - select one of our examples below.
Get Common Neighbors (out)
Find wiki pages linked to from various countries
Get Common Neighbors (in)
Find wiki pages which link to all listed countries
Parameters
Optional
Name Type Value
graph
enum
max_results
number
min_commonality
number
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.