API

Overview

We make available an API to enable you to programmatically create, retrieve, update and delete your networks within Polinode. API access is available to all users with a Polinode account.

In order to access the API you will need to generate API credentials from within the Polinode web application. The Public Key is similar to a username and the Private Key should be treated as your password. Both should be stored securely. Polinode does not store your Private Key so be sure to record both your Public Key and Private Key and to store them securely prior to closing the dialogue. You can create up to 20 key pairs from within Polinode and can delete a key pair at any time.

The documentation on this page relates to version 2 of the Polinode API.

You will find a set of example API calls authored in Python here (opens new window) and in node.js here (opens new window).

Authentication

The Polinode API uses HTTP Basic Access Authentication where your Public Key should be supplied as the username and your Private Key as the password. HTTP Basic Access Authentication is only secure if used over an HTTPS connection so it is important that you always specify https://app.polinode.com/api/v2 (opens new window) as your base route.

Compression

The Polinode API supports compression of HTTP body objects. NetworkJSON for large networks can be large and compressing the HTTP body using gzip for example can reduce the upload size by a factor of ~10x. To use compression please be sure to include the appropriate Content-Encoding header with your request, e.g. 'Content-Encoding': 'deflate'.

Base Route

The base route for the Polinode API is https://app.polinode.com/api/v2 (opens new window). It is to this route that you will add the routes detailed below. For example to GET a particular network you would use https://app.polinode.com/api/v2/networks/555194b407e3712f1beb966f (opens new window) where 555194b407e3712f1beb966f is the id of the network you are fetching.

Networks API

GET /networks

Retrieve all networks for the user.

Parameters:

None

Response on Success:

An array of all the user’s networks is returned with each element containing a network as per Format for Networks but excluding networkJSON.

GET /networks/:id

Retrieve a specific network.

URL Parameters:

Name	Type	Description
id*	String	The network id. Required.

*=required.

Response on Success:

See Format for Networks.

POST /networks

Create a new network.

Body Parameters:

See Format for Networks. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Networks. Note that networkJSON is not included in the response.

PUT /networks/:id

Edit a previously created network.

URL Parameters:

Name	Type	Description
id*	String	The network id. Required.

*=required.

Body Parameters:

See Format for Networks. Body parameters must include required keys and should not include internal keys.

Response on Success:

See Format for Networks. Note that networkJSON is not included in the response.

DELETE /networks/:id

Delete a network.

URL Parameters:

Name	Type	Description
id*	String	The network id. Required.

*=required.

Response on Success:

200

Format for Networks

Name	Level	Type	Description
_idⁱ	1	String	The network id.
billingⁱ	1	Object	Object encapsulating billing settings for the network.
maxViews	2	Number	The maximum number of views that can be saved for the network.
createdⁱ	1	Date	The date that the network was created.
description	1	String	The network description.
fileTypeⁱ	1	String	JSON or GEXF.
handpickedⁱ	1	Boolean	Whether this network is handpicked or not, i.e. is it highlighted as a handpicked network under discover.
isDirected	1	Boolean	Whether this network is directed or undirected.
modifiedⁱ	1	Date	The date that the network was last modified.
name*	1	String	Name of the network.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
originalFileTypeⁱ	1	String	Excel, JSON or GEXF.
networkUUIDⁱ	1	String	A unique identifier for the network that changes when the network JSON is updated.
status	1	String	Public or Private. Public networks are publicly available. Access to private networks is restricted.

*=required.

ⁱ=internal.

Format for Network JSON

The format of the actual network data is JSON and is detailed below.

Network JSON:

Name	Level	Type	Description
nodes*	1	Object[]	An array of node objects for the network with properties as detailed below. Required.
id*	2	String or Number	The id of the node. Required for each node.
attributes	2	Object[]	An array of attribute objects for the node. Optional.
[attribute name]	3	String or Number	For each attribute included for the node a key / value pair where the key is the name of the attribute and the value is the value of the attribute. Github flavored markdown is supported for both [attribute name] and value. There are a few special cases to be aware of: (1) If [attribute name] is ‘name’ then that value will be used for the label of the node. If no name is specified then the id of the node will be used. (2) If the first character in [attribute name] is “_” then that attribute will be included and available to size by, color by, filter by, etc. but the attribute will be hidden in the right hand side window. Please ensure that numerical attributes are of type Number rather than String. If they are Strings they will be treated as categorical attributes.
x	2	Number	The x coordinate of the node. Optional. If none is specified then nodes will be equally distributed on a circle to begin with.
y	2	Number	The y coordinate of the node. Optional. If none is specified then nodes will be equally distributed on a circle to begin with.
image	2	Object	Object encapsulating image settings for a node below. Optional.
url	3	String	A url for an image to render inside the node. Defaults to no image. Many popular services for images such as LinkedIn and Twitter will automatically add an Access-Control-Allow-Origin header to their response. However, if you use images from a URL that does not add this header you will need to prepend a third-party proxy such as https://crossorigin.me (opens new window) to the URL. For example, you may enter something like: https://crossorigin.me/http://url.com/imageName.jpg. (opens new window) Alternatively, you can upload images to a CDN such as Cloudfront and use the URLs from that CDN, being sure to enable CORS for polinode.com at a minimum.
edges	1	Object[]	An array of edge objects for the network with properties as detailed below.
id*	2	String or Number	The id of the edge. Required for each edge.
source*	2	String or Number	The id of the node where the edge starts from. If the network is undirected then source and target are interchangeable. Required for each edge.
target*	2	String or Number	The id of the node where the edge ends. If the network is undirected then source and target are interchangeable. Required for each edge.
attributes	2	Object[]	An array of attribute objects for the edge. Optional.
[attribute name]	3	String or Number	For each attribute included for the edge a key / value pair where the key is the name of the attribute and the value is the value of the attribute. Github flavored markdown is supported for both [attribute name] and value. There is one special case to be aware of: If the first character in [attribute name] is “_” then that attribute will be included and available to size by, color by, filter by, etc. but the attribute will be hidden in the right hand side window Please ensure that numerical attributes are of type Number rather than String. If they are Strings they will be treated as categorical attributes.

*=required.

Network JSON Example:

{
    'nodes':[
      {
        'id': 'Joe',
        'attributes':
        {
          'Example Numerical Attribute Name': 24,
          'Example Categorical Attribute Name': "Value 1",
          'Name': 'Joe'
        }
      },
      {
        'id':'Mary',
        'attributes':
        {
          'Example Numerical Attribute Name':38,
          'Example Categorical Attribute Name':"Value 1",
          'Name':'Mary'
        }
      },
      {
        'id':'Bill',
        'attributes':
        {
          'Example Numerical Attribute Name':65,
          'Example Categorical Attribute Name':"Value 2",
          'Name':'Bill'
        }
      },
      {
        'id':'Grant',
        'attributes':
        {
          'Example Numerical Attribute Name':52,
          'Example Categorical Attribute Name':"Value 2",
          'Name':'Grant'
        }
      }
    ],
    'edges':[
      {
        'id':0,
        'source':'Joe',
        'target':'Mary',
        'attributes':
        {
          'Example Numerical Attribute Name':30,
          'Example Categorical Attribute Name':"Value 1"
        }
      },
      {
        'id':1,
        'source':'Grant',
        'target':'Mary',
        'attributes':
        {
          'Example Numerical Attribute Name':34,
          'Example Categorical Attribute Name':"Value 1"
        }
      },
      {
        'id':2,
        'source':'Bill',
        'target':'Joe',
        'attributes':
        {
          'Example Numerical Attribute Name':38,
          'Example Categorical Attribute Name':"Value 2"
        }
      }
    ]
  };

Metrics API

ENTERPRISE USERS

The Metrics API is only available to Enterprise and Partner accounts.

Compute time for all metrics is limited to 30 seconds for each call.

Network Metrics

POST /metrics/network/modularity

Modularity is a measure of the degree to which a network is divided or separated into non-overlapping groups or communities. Whereas the Communities metric finds communities that optimises modularity, the modularity metric takes communities as an input and outputs modularity. It is a value between -1 and 1. Directed networks will be converted into undirected networks. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
attribute**	1	String	The node attribute that contains the communities to measure modularity with respect to.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

**=required

Response on Success:

A single number is returned regardless of whether networkId or networkJSON is provided.

POST /metrics/network/diameter

Diameter measures the length of the longest shortest path across the network. Only the largest connected component is considered (if applicable). Directed networks are converted to undirected networks when calculating diameter. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

A single number is returned regardless of whether networkId or networkJSON is provided.

POST /metrics/network/avgShortestPathLength

The average shortest path length of a network is the average of all shortest paths between all pairs of nodes in the network. Where two nodes cannot reach each other that path is excluded. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

A single number is returned regardless of whether networkId or networkJSON is provided.

Node Metrics

POST /metrics/nodes/averageNeighborDegree

Average Neighbor Degree for a node is the average number of edges (i.e. degree) that a node's neighbors have. For directed networks, you can specify whether to use in-degree or out-degree for each of the source and target nodes in the calculation. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
averageNeighborDegreeSource	1	String	For directed networks, either 'in' or 'out'. Defaults to 'out'.
averageNeighborDegreeTarget	1	String	For directed networks, either 'in' or 'out'. Defaults to 'out'.
directed	1	Boolean	If True then the network is a directed network. If False then the network is an undirected network. Defaults to True.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

If networkJSON is provided directly then the metric is returned as a response. If a networkID is provided then the result is saved directly on the associated networkJSON and a response of 200 is returned.

POST /metrics/nodes/betweennessCentrality

Betweenness Centrality for a node is the total number of shortest paths that pass through that node divided by the total number of shortest paths in the network. It is a measure of how much a node is a 'bridge' between other nodes in the network. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
directed	1	Boolean	If True then the network is a directed network. If False then the network is an undirected network. Defaults to True.
kPercent	1	Number	The percentage of nodes to sample (between 0 and 100). Other than for very large networks where betweenness cannot be calculated within 30 seconds, kPercent should be left at 100. Defaults to 100.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/brokerage

Brokerage here refers to Gould-Fernandez brokerage. Given an attribute, there are five kinds of brokerage possible: Coordinator, Consultant, Gatekeeper, Representative and Liaison. This metric will count up and return the number of times that a node acted in each of those roles. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
partition	1	Object	A mapping of nodes by node id to a group that will be used to calculate brokerage. Every node must be mapped to a group, i.e. each node id must be included.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/closenessCentrality

Closeness Centrality for a node is the reciprocal of its farness. The farness of a node is the sum of its shortest path distances from all other nodes. The greater a node's Closeness Centrality relative to other nodes, the closer it is on average to other nodes in the network. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
directed	1	Boolean	If True then the network is a directed network. If False then the network is an undirected network. Defaults to True.
kPercent	1	Number	The percentage of nodes to sample (between 0 and 100). Other than for very large networks where closeness cannot be calculated within 30 seconds, kPercent should be left at 100. If kPercent is less than 100 then closeness will only be calculated for the giant component (i.e. largest connected component in the network). Defaults to 100.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/constraint

Constraint is related to the concept of structural holes and measures the extent to which a node is able to take advantage of structural holes in their network. Constraint will be higher if a node's connections are highly connected between each other, either directly or indirectly through a mutual connection. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/clustering

The Clustering coefficient for a node is the fraction of possible triangles through that node that actually exist. The higher a node's clustering coefficient, the more embedded it is in the overall network. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
directed	1	Boolean	If True then the network is a directed network. If False then the network is an undirected network. Defaults to True.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/communities

Louvain Communities are non-overlapping groups of relatively closely connected nodes found by an optimization algorithm. Directed networks will be converted into undirected networks for the purposes of calculating this metric. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
allLevels	1	Boolean	The algorithm successively finds groups / communities and aggregates them. If allLevels is set to True then all the levels in this process will be outputted. If False then just the final level (with the least number of communities) will be outputted. Defaults to False. The algorithm is considerably faster if allLevels is either not set or set to False.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
resolution	1	Number	A parameter that can be used to control how many communities are outputted. Modularity is optimized (heuristically) with resolution set to to 1. A resolution of 0 will place all nodes into a single community whereas of a resolution of two times the number of nodes will result in each node being assigned it's own community. Defaults to 1.
maxSize	1	Number	An optional maximum size for the resulting communities. By default there is no maximum size. Including a maximum size will mean that the algorithm will run considerably slower.

*One and only one of these two parameters must be provided.

POST /metrics/nodes/connectedComponents

A Connected Component is a set of nodes that are connected to each other. A directed network will be treated as an undirected network for the calculation of Connected Components. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/coreNumber

Returns the core number for each node. The core number for a node is the largest value k of all k-cores containing that node where a k-core is the largest possible subgraph in the network containing nodes with a Total Degree of k or more. Core Numbers can be helpful in the decomposition of large networks. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/corePeriphery

Core Periphery will partition the network into a group of nodes that are said to be in the "Core" and a set of nodes said to be in the "Periphery". There are two options for type - Single and Multiple. If Single is chosen then the network will be partioned into a single core / periphery using the approach of Rombach et al. (2017) (opens new window). This algorithm takes two inputs - alpha and beta. Alpha is a value between 0 and 1 that determines the fuziness of the core / periphery boundary. If alpha is set to 0 the boundary is the fuzziest and if it's set to 1 the boundary is the sharpest. Beta, also between 0 and 1, is the fraction of nodes to be used for the periphery. If Multiple is selected for type then the algorithm detailed in Kojaku and Masuda (2018) (opens new window) is used. There are no input parameters for this algorithm but please note that the configuration model is used. The output of the algorithm is two attributes that are added to all nodes - Core Number and Coreness. For the Single algorithm Core Number is always 1 and Coreness is a value between 0 and 1 with values closer to 0 indicating a more peripheral node. For the Multiple algorithm there may be multiple cores as indicated by the Core Number added to each node and Coreness is a discrete value that is either 0 (periphery) or 1 (core) for the Core Number that the node is a member of. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
type	1	String	Either single or multiple. Defaults to single. Determines the type of algorithm that will be used for core / periphery detection, one that assumes a single core or one that allows for multiple potential cores.
alpha	1	Number	If type is set to single then this alpha parameter will determine the sharpness of the separation between core and periphery. Defaults to 0.5.
beta	1	Number	If type is set to single then this beta parameter will determine the proportion of peripheral nodes. Defaults to 0.8.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/currentFlowClosenessCentrality

Current Flow Closeness Centrality is similar to regular Closeness Centrality but instead of a shortest path measure for distance, effective resistance inspired by electric circuit models is used. Directed networks will be converted to undirected networks. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/effectiveSize

Effective Size is related to the concept of structural holes and the reduncancy of connections. It measures the number of people that the node is connected to but controlling for (i.e. reducing by) the redundancy of those connections. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/efficiency

Efficiency is equal to effective size divided by total degree. If a node has no redundant ties then the effective size will be equal to total degree and efficiency will be equal to one. Efficiency is the proportion of a node's ties that are non-redundant. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/eigenvectorCentrality

Eigenvector Centrality is motivated by the idea that nodes connected to other nodes that are central should themselves be relatively central, i.e. being connected to a central node contributes more than being connected to a non-central node. It is not always well defined for directed networks and it's generally preferable to calculate Katz Centrality for directed networks. However, should you calculate eigenvector centrality for a directed network Polinode will return "left" eigenvector centrality (i.e. corresponding to the in-edges). Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/externalVsInternal

External vs Internal (EI) calculates, for a given attribute, the percentage of a node's edges that connect to nodes that do not share the same value for that attribute (external connections) vs connections to nodes that do share the same attribute value (internal connections). If type is Total the metric will be calculated for all edges, if type is In then the metric will be calculated only for a node's incoming edges and if type is Out then only for a node's outgoing edges.

Body Parameters:

Name	Level	Type	Description
attribute	1	String	The attribute that external vs internal is calculated with respect to.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
type	1	String	How to calculate the metric - 'total', 'in' or 'out'. Defaults to 'total.'

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/harmonicCentrality

Harmonic Centrality for a node is the sum of the reciprocals of the shortest path distances from that node to each other node in the network. It is closely related to Closeness Centrality with the key difference being that the reciprocal is taken for each distance rather than taking the reciprocal of the sums of the distances. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/HITS

Hyperlink-Induced Topic Search (HITS) for a node gives two metrics - Hubs and Authorities. A node has a relatively high Hubs score if it links to other nodes and a relatively high Authority score if it is linked to by other nodes. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/identifyInfluencers

Identify Influencers is a heuristic that finds the most influential nodes in the network in the sense that together the count of those nodes and the nodes connected to those nodes (in either direction for directed networks) is maximised, i.e. coverage of the network is maximised.

Body Parameters:

Name	Level	Type	Description
direction	1	String	One of 'total', 'in' or 'out'. Defaults to 'total'.
identifyInfluencersAttribute	1	String	An optional name of an attribute that the algorithm will limit the identification of influencers with respect to.
identifyInfluencersAttributeValues	1	Array	An optional array of attribute values for the identifyInfluencersAttribute that the algorithm will limit the identification of influencers to, i.e. influencers must have one of these values for the identified attribute
identifyInfluencersMethod	1	String	The method to use, either 'coverage' or 'count'. Defaults to 'coverage'.
influencersCount	1	Number	If the method is 'count', the total number of influencers to target.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
targetCoveragePercent	1	Number	If the method is 'coverage', the percentage coverage to target (between 0 and 100). Defaults to 90.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/inDegree

In Degree for a node is a straightforward measure of centrality - it measures the total number of nodes linking to that node. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
type	1	String	Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/kCliqueCommunities

A K Clique Community is the union of all cliques of size k that can be reached through adjacent k-cliques where a k-clique is a group of k nodes that are all connected to each other and a k-clique is said to be adjacent to another k-clique if it shares k-1 nodes with it. Communities produced by this algorithm are generally not distinct and will overlap so an attribute is added for each community found. Directed networks will be converted to undirected networks for the puroses of calculating this metric. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
kCliqueCommunities	1	Number	The clique size, k. Defaults to 2.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/katzCentrality

Katz Centrality for a node takes into account not just the neighbors of that node but also their neighbors and so on, applying an attenuation factor of alpha so that the influence of nodes declines on every step away from the target node. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
katzCentralityAlpha	1	Number	Attenuation factor. Defaults to 0.1.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/loadCentrality

Load Centrality for a node is the total amount of some commodity passing through that node when one unit of the commodity is sent from each node in the network to each other node in the network and the commodity is split equally at branching points and aggregated at meeting points.. Load Centrality is very similar to Betweenness Centrality and also measures 'bridging'. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/outDegree

Out Degree for a node is a straightforward measure of centrality - it measures the total number of nodes that that node links to. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
type	1	String	Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/pagerank

Pagerank for a node is a ranking of relative importance in the network based on the structure of incoming edges for that node. It was originally designed to rank web pages. Similar to Katz Centrality, alpha is an attenuation factor. Pagerank for undirected networks will be calculated by transforming each undirected edge into two directed edges. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
pagerankAlpha	1	Number	Attenuation factor. Defaults to 0.85.
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.

*One and only one of these two parameters must be provided.

Response on Success:

POST /metrics/nodes/totalDegree

Total Degree for a node is a straightforward measure of centrality. It is simply the total number of edges that that node has, i.e. for directed networks it is the sum of In Degree and Out Degree. Read more here (opens new window).

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
type	1	String	Either 'sum' or 'average'. If metricEdgeWeights is True or a string then type determines how those edge weights will be used, either summed or averaged.

*One and only one of these two parameters must be provided.

Response on Success:

Edge Metrics

POST /metrics/edges/edgeBetweennessCentrality

Edge betweenness is a measure of the total number of shortest path in the network that pass through an edge relative to the total number of shortest paths in the network overall.

Body Parameters:

Name	Level	Type	Description
metricEdgeWeights	1	String or Boolean	If True then the weight value on edges will be used, if a string is provided then that edge attribute will be used as the edge weight.
networkId*	1	String	The Id of the network on which to run the metric. If provided, the network will be retrieved and the metric run. The resulting metric values will then be saved as an attribute on each node in the network, i.e. the networkJSON for that network will be updated.
networkJSON*	1	Object	A JSON object containing the network data. See Format for Network JSON.
normalized	1	Boolean	If True then the metric will be normalized. Defaults to True.

*One and only one of these two parameters must be provided.

Response on Success:

Responses API

ENTERPRISE USERS

The Responses API is only available to Enterprise and Partner accounts.

GET /responses/:id

Retrieve a specific response.

URL Parameters:

Name	Type	Description
id*	String	The response id. Required. This may be obtained in real-time via the Webhook on Completion or by downloading the full Respondent List.

*=required.

Response on Success:

Please contact us for details on the format of responses.

Surveys API

ENTERPRISE USERS

The Surveys API is only available to Enterprise and Partner accounts.

POST /surveys/export/:id

Initiates an export of survey data, i.e. a combination of lists and responses. Please note that this starts a worker job that may take ~10 minutes to complete for larger surveys. This route should not be called more than once per day per survey.

URL Parameters:

Name	Type	Description
id*	String	The survey id. Required.

*=required.

Response on Success:

Will return the survey object on success (please contact support for details if needed). If the survey is already generating (i.e. export is in progress) then it will return an HTTP 200 OK success status response code.

GET /surveys/export/:id

Once the worker job is completed, this route will return a URL that can be used to retrieve the survey export (i.e. combined lists and responses). It will return {generatingSurveyJSON: true} if the survey is still generating. The returned URL is valid for 5 minutes.

URL Parameters:

Name	Type	Description
id*	String	The survey id. Required.

*=required.

Response on Success:

If the survey generation is complete it will return a URL to retrieve the export in the format {AWSURL: valueOfURL}. The returned URL is valid for 5 minutes. The route will return {generatingSurveyJSON: true} if the survey is still generating.

← FAQ