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.
  color 2 String The color to display the node in. Optional. Since you can color nodes by any attribute it is generally better to include the attribute that you want to color by under attributes. Though if you wanted every node to have a unique color you could do so here. If specified, color should be a rgba format string. For example, ‘rgba(120, 120, 120, 1)’.
  size 2 Number A number representing the relative size of nodes. Optional. Since you can size nodes by any attribute it is generally better to include the attribute that you want to size by under attributes.
  type 2 String The shape of the node. Optional, defaults to circle. Available options are: ‘circle’, ‘star’, ‘triangle’, ‘diamond’ and ‘square’.
  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.
    scale 3 Number Increase or decrease the size of the image. Useful when you have a square image from LinkedIn or Twitter say and would like to expand it to fill a circular node. Optional, the default is 1.3 for nodes without a type specified as they will be rendered as circles and 1 if a node type is specified.
    clip 3 Number Removes a portion of the image (from the edge of the image). Useful when you would like a border around the image after expanding the image using scale. Optional, the default is 0.85 for nodes without a type specified as they will be rendered as circles and 1 if a node type is specified.
  icon 2 Object Object encapsulating icon settings for a node below. Optional.
    font 3 String The name of the font to use for icons. There is currently only one option - ‘FontAwesome’ and this value is required if an icon is specified for the node.
    content 3 String The Unicode identifier for a Font Awesome icon to show at the center of the node. For a full list of available icons please visit this (opens new window) link. For example, to display an anchor you would enter ‘f13d’. Required if an icon is specified for the node.
    color 3 String The color of the icon displayed for a node in rgba format. Optional, the default is white, i.e. ‘rgba(255, 255, 255, 1)’.
    scale 3 Number Increase or decrease the size of the icon. Optional, the default is 1.
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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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/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:

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.

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:

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.