NAV
shell ruby python


Introduction

API Endpoint

https://graphcommons.com/api/v1
https://graphcommons.com/api/v1
https://graphcommons.com/api/v1

Graph Commons provides a simple REST API to programmatically create network maps (graphs) and integrate network intelligence into your own applications. You can use the API endpoints to read and write graphs, nodes, and edges on the platform. JSON is returned by all API responses.

Graph Commons API libraries & examples are available in several languages. Also see the hackathon documentations for API uses cases.

Authentication

Example request with your API key

curl -XGET "https://graphcommons.com/api/v1/status"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/status") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end

c.perform
# make sure to install graphcommons first
# pip install graphcommons

from graphcommons import GraphCommons

graphcommons = GraphCommons('<YOUR_API_KEY>')

You authenticate to the Graph Commons API by providing your secret API KEY in the request header.

To get started, sign up to Graph Commons and get your developer key, which will be used for authentication in your API calls. Your API keys carry many privileges, so be sure to keep them secret!

Endpoints

GET /status

Example request

curl -XGET "https://graphcommons.com/api/v1/status"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/status") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end

c.perform

from graphcommons import GraphCommons

graphcommons = GraphCommons('<YOUR_API_KEY>')
print(graphcommons.status())

Example response in JSON

{
  "msg": "Working"
}

This endpoint is a simple way to make sure your client can query Graph Commons API. It does not do anything other than returning a success message for valid queries.

HTTP Request

GET https://graphcommons.com/api/v1/status

Query Parameters

No query parameters necessary for this endpoint.

GET graphs/:id

curl https://graphcommons.com/api/v1/graphs/5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a
  -H 'Authentication: <YOUR_API_KEY>'
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/graphs/5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
from graphcommons import GraphCommons

graphcommons = GraphCommons('<YOUR_API_KEY>')
graph = graphcommons.graphs('5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a')
print(graph.name)

for node in graph.nodes:
    print(node.name)
    print(graph.edges_from(node))  # edges directed from the node
    print(graph.edges_to(node))  # edges directed to the node

Example response

{
    "graph": {
        "created_at": "2016-01-05T19:19:57.000+00:00",
        "description": null,
        "edgeTypes": [
            {
                "color": "#1f77b4",
                "description": null,
                "directed": 0,
                "durational": null,
                "id": "5fb75574-8a2d-c4d8-cad3-0ed1bb9b02ad",
                "name": "COLLABORATED",
                "name_alias": null,
                "properties": [],
                "weighted": 1
            }
        ],
        "edges": [
            {
                "directed": 0,
                "from": "3ed6b0ec-9eb1-c6ba-6b94-e84482d05546",
                "id": "a7f39d26-1888-e5ac-bea7-d4f19a01ad03",
                "name": "COLLABORATED",
                "properties": {},
                "to": "d08ff048-2850-747b-b9f1-eb9944e57937",
                "type_id": "5fb75574-8a2d-c4d8-cad3-0ed1bb9b02ad",
                "user_id": "d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
                "weight": 1
            }
        ],
        "id": "5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a",
        "image": {
            "path": "/system/graphs/missing.png",
            "ref_name": null,
            "ref_url": null
        },
        "layout": {
            "algorithm": "force_directed",
            "dragCoeff": 0.02,
            "gravity": -2.4,
            "springCoeff": 0.0002,
            "springLength": 100,
            "theta": 0.8,
            "transform": "matrix(1, 0, 0, 1, 0, 0)"
        },
        "license": {
            "cc_by": true,
            "cc_nc": false,
            "cc_nd": false,
            "cc_sa": true,
            "type": "cc"
        },
        "name": "my api graph",
        "nodeTypes": [
            {
                "color": "#d62728",
                "description": null,
                "hide_name": null,
                "id": "faae51a2-a493-ff9f-7d98-cda31097a375",
                "image": null,
                "image_as_icon": true,
                "name": "Person",
                "name_alias": null,
                "properties": [],
                "size": "metric_degree",
                "size_limit": 48
            }
        ],
        "nodes": [
            {
                "analysis": {
                    "degree_centrality": 1,
                    "in_degree_centrality": 1,
                    "out_degree_centrality": 0
                },
                "description": "machine-readable artist",
                "id": "d08ff048-2850-747b-b9f1-eb9944e57937",
                "image": "",
                "name": "Burak",
                "properties": {},
                "reference": "",
                "type": "Person",
                "type_id": "faae51a2-a493-ff9f-7d98-cda31097a375"
            },
            {
                "analysis": {
                    "degree_centrality": 1,
                    "in_degree_centrality": 0,
                    "out_degree_centrality": 1
                },
                "description": "a person",
                "id": "3ed6b0ec-9eb1-c6ba-6b94-e84482d05546",
                "image": "",
                "name": "Ahmet",
                "properties": {},
                "reference": "",
                "type": "Person",
                "type_id": "faae51a2-a493-ff9f-7d98-cda31097a375"
            }
        ],
        "status": 0,
        "subtitle": null,
        "updated_at": "2016-01-05T19:19:58.000+00:00",
        "users": [
            {
                "first_name": "",
                "fullname": "ahmetkizilay",
                "id": "d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
                "img_path": "/system/users/images/d012995d-2e9b-43b9-a1a6-677fb4ef8f40/original/avatar.jpeg",
                "is_admin": true,
                "is_owner": true,
                "last_name": "",
                "username": "ahmetkizilay"
            }
        ]
    }
}

This endpoint returns the graph data along with its nodes, edges, node types, edge types, and the editors.

HTTP Request

GET https://graphscommons.com/api/v1/graphs/:id

URL Parameters

Parameter Description
ID The ID of the graph to retrieve

POST /graphs

curl -XPOST https://graphcommons.com/api/v1/graphs
  -H 'Authentication: <YOUR_API_KEY>'
  -H 'Content-Type: application/json'
  -d '
    {
      "name": "My algorithmically generated graph",
      "description": "",
      "status": 0,
      "signals": [
        {
          "action": "edge_create",
          "from_name": "Ahmet",
          "from_type": "Person",
          "to_name": "Burak",
          "to_type": "Person",
          "name": "COLLABORATED",
          "weight": 2
        }
      ]
    }
  '
require 'curl'

graph_body = Hash.new
graph_body[:name] = "My algorithmically generated graph"
graph_body[:description] = "I can use graphs within my application"
graph_body[:status] = 0

# adding two signals here
graph_body[:signals] = Array.new
graph_body[:signals] << {
  :action => "node_create",
  :name => "Ahmet",
  :type => "Person",
  :description => "nice guy"
}
graph_body[:signals] << {
  :action => "edge_create",
  :from_name => "Ahmet",
  :from_type => "Person",
  :to_name => "Burak",
  :to_type => "Person",
  :name => "COLLABORATED",
  :weight => 2
}

c = Curl::Easy.http_post("https://graphcommons.com/api/v1/graphs", graph_body.to_json) do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
from graphcommons import GraphCommons, Signal

graphcommons = GraphCommons('<YOUR_API_KEY>')

graph = graphcommons.new_graph(
    name="My algorithmically generated graph",
    description="I can use graphs within my application",
    signals=[
        Signal(
            action="node_create",
            name="Ahmet",
            type="Person",
            description="nice guy"
        ),
        Signal(
            action="edge_create",
            from_name="Ahmet",
            from_type="Person",
            to_name="Burak",
            to_type="Person",
            name="COLLABORATED",
            weight=2
        )
    ]
)

print(graph.id)  # added graph's id

Example response

{
  "graph":{
    "id":"1c9e0d69-b26a-4d0e-9e3a-7149aa4a636e",
    "name":"My algorithmically generated graph",
    "description": "I can use graphs within my application",
    "subtitle":null,
    "status":0,
    "created_at":"2015-09-11T11:49:13.000+00:00",
    "signals":[
      {
        "action":"nodetype_create",
        "id":"97f5c4fb-8331-4fc7-9ce2-ce7e4eb7810d",
        "name":"Person",
        "color":"#bcbd22",
        "properties":[

        ],
        "image_as_icon":false,
        "size":"metric_degree",
        "size_limit":48,
        "status":0
      },
      {
        "action":"node_create",
        "name":"Ahmet",
        "type":"Person",
        "description":"nice guy",
        "id":"5622191d-04fb-4fdd-952d-c5a919ca4d46",
        "type_id":"97f5c4fb-8331-4fc7-9ce2-ce7e4eb7810d",
        "image":"",
        "reference":""
      },
      {
        "action":"edgetype_create",
        "id":"e697f7f9-9002-4f7c-8af2-027aefcf8908",
        "name":"COLLABORATED",
        "color":"#1f77b4",
        "weighted":1,
        "directed":1,
        "status":0
      },
      {
        "action":"node_create",
        "id":"793bfa58-67e0-44f8-ac9c-2b324ff5223b",
        "name":"Burak",
        "type":"Person",
        "type_id":"97f5c4fb-8331-4fc7-9ce2-ce7e4eb7810d",
        "properties":{

        },
        "description":"",
        "image":"",
        "reference":""
      },
      {
        "action":"edge_create",
        "from_name":"Ahmet",
        "from_type":"Person",
        "to_name":"Burak",
        "to_type":"Person",
        "name":"COLLABORATED",
        "weight":2,
        "from":"5622191d-04fb-4fdd-952d-c5a919ca4d46",
        "to":"793bfa58-67e0-44f8-ac9c-2b324ff5223b",
        "id":"eaab1c2f-0d42-49d4-ab96-87fb5af0aeb5",
        "name_id":"e697f7f9-9002-4f7c-8af2-027aefcf8908",
        "directed":1
      }
    ]
  }
}

This endpoint creates a graph. Basic properties such as name, description and status can be assigned inside the request body.

To create nodes and edges, pass graph signals into the body, after the basic graph info.

HTTP Request

POST https://graphcommons.com/api/v1/graphs

URL Parameters

There are no url parameters for this endpoint.

Request body

Parameter Description
name name of the graph
subtitle subtitle of the graph
description a short description of the graph
status initial status of the graph (0 => Work in progress, 1 => published, 2 => private)

Response body

The response body will be a simplified JSON representation of the created graph.

If signals were passed in the request, the response body will return the same signals (nodes, edges, and their types) with their newly assigned id values for nodes and edges.

PUT graphs/:id

curl -XPUT https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958 \
  -H 'Authentication: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '
    {
      "graph": {
        "name": "New name",
        "description": "New description",
        "subtitle": "New subtitle"
      }
    }
  '
require 'curl'

graph_body = Hash.new

graph_body[:graph] =  {
  :name => "New name",
  :description => "New description",
  :subtitle => "New subtitle"
}

c = Curl::Easy.http_put("https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958", graph_body.to_json) do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
   "obj":"Graph",
   "id":"5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a",
   "name":"New name",
   "subtitle":"New subtitle",
   "description": "New description",
   "status":0,
   "status_text":"Work In Progress",
   "image_url":null,
   "nodes_count":2,
   "created_at":1452021597,
   "updated_at":1452025786,
   "owner":{
      "id":"d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
      "username":"ahmetkizilay",
      "image_url":"https://graphcommons.com/system/users/images/d012995d-2e9b-43b9-a1a6-677fb4ef8f40/original/avatar.jpeg",
      "url":"https://graphcommons.com/users/d012995d-2e9b-43b9-a1a6-677fb4ef8f40"
   },
   "hubs":[

   ]
}

This endpoint allows editors of the graph to update some properties of a graph. Currently, updating name, description and subtitle is supported.

HTTP Request

PUT https://graphcommons.com/api/v1/graphs/:id

URL Parameters

Parameter Description
ID The ID of the graph to add signals

Response body

The response will be a graph object with basic properties of the graph. The response won’t contain any nodes and edge data.

PUT graphs/:id/add

curl -XPUT https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958/add
  -H 'Authentication: <YOUR_API_KEY>'
  -H 'Content-Type: application/json'
  -d '
    {
      "signals": [
        {
          "action": "edge_create",
          "from_name": "Ahmet",
          "from_type": "Person",
          "to_name": "Fatih",
          "to_type": "Person",
          "name": "COLLABORATED",
          "weight": 2
        }
      ]
    }
  '
require 'curl'

graph_body = Hash.new

# adding two signals here
graph_body[:signals] = Array.new
graph_body[:signals] << {
  :action => "edge_create",
  :from_name => "Ahmet",
  :from_type => "Person",
  :to_name => "Fatih",
  :to_type => "Person",
  :name => "COLLABORATED",
  :weight => 1
}

c = Curl::Easy.http_put("https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958/add", graph_body.to_json) do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
from graphcommons import GraphCommons, Signal

graphcommons = GraphCommons('<YOUR_API_KEY>')
graphcommons.update_graph(
    id="7141da86-2a40-4fdc-a7ac-031b434b9653",
    signals=[
        Signal(
            action="node_create",
            name="Ahmet",
            type="Person",
            description="nice guy"
        ),
        Signal(
            action="edge_create",
            from_name="Ahmet",
            from_type="Person",
            to_name="Burak",
            to_type="Person",
            name="COLLABORATED",
            weight=2
        )
    ]
)

Example response

{
  "graph":{
    "id":"1c9e0d69-b26a-4d0e-9e3a-7149aa4a636e",
    "name":"My first api graph",
    "description":null,
    "subtitle":null,
    "status":0,
    "created_at":"2015-09-11T11:49:13.000+00:00",
    "signals":[
      {
        "action":"node_create",
        "id":"6be91b8e-8c46-4c50-868e-934a06bd8ece",
        "name":"Fatih",
        "type":"Person",
        "type_id":"97f5c4fb-8331-4fc7-9ce2-ce7e4eb7810d",
        "properties":{

        },
        "description":"",
        "image":"",
        "reference":""
      },
      {
        "action":"edge_create",
        "from_name":"Ahmet",
        "from_type":"Person",
        "to_name":"Fatih",
        "to_type":"Person",
        "name":"COLLABORATED",
        "weight":2,
        "from":"5622191d-04fb-4fdd-952d-c5a919ca4d46",
        "to":"6be91b8e-8c46-4c50-868e-934a06bd8ece",
        "id":"5029f3bc-2da2-43be-b00a-12a63ee95898",
        "name_id":"e697f7f9-9002-4f7c-8af2-027aefcf8908",
        "directed":1
      }
    ]
  }
}

This endpoint sends signals to an existing graph to update its contents. The signals are passed in the request body as JSON.

HTTP Request

PUT https://graphcommons.com/api/v1/graphs/:id/add

URL Parameters

Parameter Description
ID The ID of the graph to add signals

Response body

The response body will be a simplified JSON representation of the current graph. The response will also contain a mirror of the request signals with the newly created ids for the new nodes and edges.

GET graphs/:id/types

curl -XGET 'https://graphcommons.com/api/v1/graphs/d14c0906-415e-4639-8173-ccbc2728421a/types'
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/graphs/d14c0906-415e-4639-8173-ccbc2728421a/types") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
    "edgetypes": [
        "MENTIONS",
        "WROTE"
    ],
    "id": "d14c0906-415e-4639-8173-ccbc2728421a",
    "name": "mention network",
    "nodetypes": [
        "message",
        "person"
    ]
}

This endpoint gives a simple summary of all node types and edge types in a graph.

HTTP Request

GET https://graphcommons.com/api/v1/graphs/:id/types

URL Parameters

Parameter Description
id the ID of the graph

GET graphs/:id/edges

curl -XGET 'https://graphcommons.com/api/v1/graphs/5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a/edges?from=d08ff048-2850-747b-b9f1-eb9944e57937&to=3ed6b0ec-9eb1-c6ba-6b94-e84482d05546&directed=false'
 -H 'Authentication: <YOUR API KEY>'
 -H 'Content-Type: application/json'
c = Curl::Easy.http_get("https://graphcommons.com/api/v1/graphs/5bf40f0a-50b5-4e51-9bec-1c664f9b1a8a/edges?from=d08ff048-2850-747b-b9f1-eb9944e57937&to=3ed6b0ec-9eb1-c6ba-6b94-e84482d05546&directed=false", graph_body.to_json) do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
  "msg": "Edge exists"
}

This endpoint checks if two nodes are connected with an edge inside a graph. Returns 200 if an edge exists between two nodes,

HTTP Request

GET https://graphcommons.com/api/v1/graphs/:id/edges?from=<NODE-ID>&to=<NODE-ID>

URL Parameters

Parameter Description
ID The ID of the graph
from the ID of the source node
to the ID of the target node
directed specify if the edge is directed, OPTIONAL, DEFAULT true

HTTP Response

Returns 200, when an edge exists between two nodes

Returns 404, when specified nodes are not connected by an edge

GET graphs/:id/paths

curl -XGET https://graphcommons.com/api/v1/graphs/d14c0906-415e-4639-8173-ccbc2728421a/paths?from=faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593&to=fb908e54-654d-bc3e-f282-f3a5119dc27e
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/graphs/d14c0906-415e-4639-8173-ccbc2728421a/paths?from=faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593&to=fb908e54-654d-bc3e-f282-f3a5119dc27e") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
    "edges": {
        "0c40cf23-9668-49ac-d949-67a20f63cb0d": {
            "color": "#9467bd",
            "directed": true,
            "edge_type": "MENTIONS",
            "from": "d6df50ce-47a1-e369-80d2-04ccfb19bc0f",
            "id": "0c40cf23-9668-49ac-d949-67a20f63cb0d",
            "obj": "Relation",
            "reference": null,
            "to": "fb908e54-654d-bc3e-f282-f3a5119dc27e",
            "type_id": "d0f64fc1-446b-bdeb-efcc-05e7f53b82f9",
            "weight": 1
        },
        "163540b6-9850-642d-833d-2dc5acc10d85": {
            "color": "#d62728",
            "directed": true,
            "edge_type": "WROTE",
            "from": "faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593",
            "id": "163540b6-9850-642d-833d-2dc5acc10d85",
            "obj": "Relation",
            "reference": null,
            "to": "d6df50ce-47a1-e369-80d2-04ccfb19bc0f",
            "type_id": "d3ef89c0-eace-5e69-87b7-749ba1f05534",
            "weight": 1
        }
    },
    "nodes": {
        "d6df50ce-47a1-e369-80d2-04ccfb19bc0f": {
            "created_at": 1452193796,
            "description": "",
            "id": "d6df50ce-47a1-e369-80d2-04ccfb19bc0f",
            "image": "",
            "name": "m2",
            "obj": "Node",
            "reference": "",
            "type": {
                "color": "#2ca02c",
                "id": "602f3445-6e1c-0669-9569-eae19bc8e08e",
                "name": "message"
            },
            "updated_at": 1452193796,
            "url": "https://graphcommons.com/nodes/d6df50ce-47a1-e369-80d2-04ccfb19bc0f"
        },
        "faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593": {
            "created_at": 1452193796,
            "description": "",
            "id": "faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593",
            "image": "",
            "name": "mehmet",
            "obj": "Node",
            "reference": "",
            "type": {
                "color": "#e377c2",
                "id": "68d564ff-3c69-c6e7-b1e0-e4f8637fb990",
                "name": "person"
            },
            "updated_at": 1452193796,
            "url": "https://graphcommons.com/nodes/faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593"
        },
        "fb908e54-654d-bc3e-f282-f3a5119dc27e": {
            "created_at": 1452193796,
            "description": "",
            "id": "fb908e54-654d-bc3e-f282-f3a5119dc27e",
            "image": "",
            "name": "saffet",
            "obj": "Node",
            "reference": "",
            "type": {
                "color": "#e377c2",
                "id": "68d564ff-3c69-c6e7-b1e0-e4f8637fb990",
                "name": "person"
            },
            "updated_at": 1452193796,
            "url": "https://graphcommons.com/nodes/fb908e54-654d-bc3e-f282-f3a5119dc27e"
        }
    },
    "paths": [
        {
            "dirs": [
                "out",
                "out"
            ],
            "edges": [
                "163540b6-9850-642d-833d-2dc5acc10d85",
                "0c40cf23-9668-49ac-d949-67a20f63cb0d"
            ],
            "nodes": [
                "faacbe4a-44c2-cbb6-5f1e-4aefa6dd3593",
                "d6df50ce-47a1-e369-80d2-04ccfb19bc0f",
                "fb908e54-654d-bc3e-f282-f3a5119dc27e"
            ],
            "path_string": "(mehmet) - [WROTE] -> (m2) - [MENTIONS] -> (saffet)"
        }
    ]
}

This endpoint returns paths between nodes inside a graph. See the detailed path documentation below.

HTTP Request

GET https://graphcommons.com/api/v1/graphs/:id/paths

URL Parameters

Parameter Description
ID The ID of the graph
from the ID of the node to start from
to the ID of the node to end at
fromtype the node type to start from
totype the node type to end at
via the list of accepted edge types for paths
strict set to true to force paths to match via pattern exactly
depth max depth for paths
not ensure start and end nodes are not connected by the specified edge type
limit number of paths to return
skip number of paths to skip

GET graphs/:id/collab_filter

curl -XGET "https://graphcommons.com/api/v1/graphs/19dba76e-9aa4-4abe-9502-93525bceae7d/collab_filter?from=a048e14a-ef31-49c9-a937-4b499b91caa1&via=MEMBER_OF"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/graphs/19dba76e-9aa4-4abe-9502-93525bceae7d/collab_filter?from=a048e14a-ef31-49c9-a937-4b499b91caa1&via=MEMBER_OF") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
  "suggestions": [
    {
      "node": {
        "created_at": 1452107498,
        "description": "",
        "id": "085d790a-577f-4006-b3c9-276cd5824664",
        "image": "",
        "name": "ifadeozgurlugu",
        "obj": "Node",
        "properties": {
          "channel_id": "C0AHKBJ06"
        },
        "reference": "",
        "type": {
          "color": "#8c564b",
          "id": "ce6afe52-b87a-460c-8db3-e3c94be5c99a",
          "name": "Channel"
        },
        "updated_at": 1452107498,
        "url": "https://graphcommons.com/nodes/085d790a-577f-4006-b3c9-276cd5824664"
      },
      "path_count": 42,
      "probability": 0.22459893048128343
    },
    {
      "node": {
        "created_at": 1452107498,
        "description": "",
        "id": "d8d9de40-6ba2-4e7d-b692-532a5933c0fd",
        "image": "",
        "name": "egitim",
        "obj": "Node",
        "properties": {
          "channel_id": "C0AHUQEBC"
        },
        "reference": "",
        "type": {
          "color": "#8c564b",
          "id": "ce6afe52-b87a-460c-8db3-e3c94be5c99a",
          "name": "Channel"
        },
        "updated_at": 1452107498,
        "url": "https://graphcommons.com/nodes/d8d9de40-6ba2-4e7d-b692-532a5933c0fd"
      },
      "path_count": 34,
      "probability": 0.18181818181818182
    }
  ]
}

This endpoint suggests edges for a given node, based on the number of shared neighbors with other nodes in the graph. This endpoint can be used for the classical recommendation case, such as, what other books are purchased by people who purchased the same book as I did. See the detailed path documentation below.

HTTP Request

GET https://graphcommons.com/api/v1/graphs/:id/collab_filter

URL Parameters

Parameter Description
ID The ID of the graph
from the ID of the node to get suggestions for
via the edge type for which the suggestions will be calculated
among the edge type pattern to specify the group of nodes to compare common neighbors.
curl -XGET "https://graphcommons.com/api/v1/graphs/search?query=coffee"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/graphs/search?query=coffee") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

[
    {
        "created_at": 1442130637,
        "description": "",
        "hubs": [],
        "id": "7f034b0a-ebf3-4003-b532-36fcd11f3cd7",
        "image_url": "https://graphcommons.com/system/graphs/images/7f034b0a-ebf3-4003-b532-36fcd11f3cd7/original/header-bg3.jpg",
        "name": "Third Wave Coffee Shops in Turkey",
        "nodes_count": 63,
        "obj": "Graph",
        "owner": {
            "id": "85dbf926-cd78-4dbc-bf4e-a005b7c26d38",
            "image_url": "https://graphcommons.com/system/users/images/85dbf926-cd78-4dbc-bf4e-a005b7c26d38/original/1974995_516433968503036_7369492924096915644_n.jpg",
            "url": "https://graphcommons.com/users/85dbf926-cd78-4dbc-bf4e-a005b7c26d38",
            "username": "ceaksan"
        },
        "status": 1,
        "status_text": "Published",
        "subtitle": "",
        "updated_at": 1451814750
    },
    {
        "created_at": 1417793150,
        "description": "",
        "hubs": [],
        "id": "c7a0590c-60cf-49ca-910a-1bd5940ce2c2",
        "image_url": "https://graphcommons.com/system/graphs/images/c7a0590c-60cf-49ca-910a-1bd5940ce2c2/original/c7a0590c-60cf-49ca-910a-1bd5940ce2c2.png",
        "name": "Our Third Wave Coffee",
        "nodes_count": 35,
        "obj": "Graph",
        "owner": {
            "id": "db35b4cd-b260-40ee-b921-4c503d7f070a",
            "image_url": "http://www.gravatar.com/avatar/2783268d0c97e51e5d18d39951d6ee57?default=https%3A%2F%2Fgraphcommons.com%2Fsystem%2Fusers%2Fmissing.png",
            "url": "https://graphcommons.com/users/db35b4cd-b260-40ee-b921-4c503d7f070a",
            "username": "dara"
        },
        "status": 0,
        "status_text": "Work In Progress",
        "subtitle": "",
        "updated_at": 1447464024
    },
    {
        "created_at": 1367940227,
        "description": "Coffee typologies veering away from espresso",
        "hubs": [],
        "id": "adfd49b7-f799-4b07-869a-3d42f4728cef",
        "image_url": "https://graphcommons.com/system/graphs/images/adfd49b7-f799-4b07-869a-3d42f4728cef/original/adfd49b7-f799-4b07-869a-3d42f4728cef.png",
        "name": "Complicated Caffiene",
        "nodes_count": 83,
        "obj": "Graph",
        "owner": {
            "id": "8ba5aa9a-9990-4328-acde-3058731f9924",
            "image_url": "http://www.gravatar.com/avatar/6cfa21e06a9882cfbf95333d98252534?default=https%3A%2F%2Fgraphcommons.com%2Fsystem%2Fusers%2Fmissing.png",
            "url": "https://graphcommons.com/users/8ba5aa9a-9990-4328-acde-3058731f9924",
            "username": "corinnequin"
        },
        "status": 0,
        "status_text": "Work In Progress",
        "subtitle": null,
        "updated_at": 1434032738
    }
]

This endpoint lets you search for Graphs in Graph Commons.

To limit the scope of the query to a specific hub or graph, supply the id of the hub along with the query. See the parameters table below for more options.

HTTP Request

GET https://graphcommons.com/api/v1/graphs/search

URL Parameters

Parameter Description
query query to be searched
hub id of the hub to search in
limit limit the number of results (max: 20)
skip number of results to skip

DELETE graphs/:id

curl -XDELETE https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/graphs/1b1cbad8-04cb-4131-aa57-00f7aaee958") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{ "msg": "Graph deleted"}

This endpoint deletes a graph.

HTTP Request

DELETE https://graphcommons.com/api/v1/graphs/:id

URL Parameters

Parameter Description
ID The ID of the graphs to delete

GET nodes/:id

curl -XGET https://graphcommons.com/api/v1/nodes/1b1cbad8-04cb-4131-aa57-00f7aaee958
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/nodes/1b1cbad8-04cb-4131-aa57-00f7aaee958") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
from graphcommons import GraphCommons
graphcommons = GraphCommons('<YOUR_API_KEY>')

print(graphcommons.nodes('6be91b8e-8c46-4c50-868e-934a06bd8ece'))

Example response

{
  "node":{
    "id":"6be91b8e-8c46-4c50-868e-934a06bd8ece",
    "name":"Fatih",
    "type":"Person",
    "type_id":"97f5c4fb-8331-4fc7-9ce2-ce7e4eb7810d",
    "description":"",
    "image":"",
    "created_at":"2015-09-11T12:10:52.000+00:00",
    "updated_at":"2015-09-11T12:10:52.000+00:00",
    "graphs_count":1,
    "graphs":[
      {
        "id":"1c9e0d69-b26a-4d0e-9e3a-7149aa4a636e",
        "name":"My first api graph"
      }
    ],
    "hubs":[

    ],
    "users":[
      {
        "id":"d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
        "username":"ahmetkizilay"
      }
    ]
  }
}

This endpoint retrieves a node and all its properties.

HTTP Request

GET https://graphcommons.com/api/v1/nodes/:id

URL Parameters

Parameter Description
ID The ID of the node to retrieve
curl -XGET "https://graphcommons.com/api/v1/nodes/search?query=istanbul&limit=1"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/nodes/search?query=istanbul&limit=1") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform

Example response

{
    "nodes": [
        {
            "description": null,
            "graphs": [
                {
                    "id": "c7a0590c-60cf-49ca-910a-1bd5940ce2c2",
                    "image_url": "https://graphcommons.com/system/graphs/images/c7a0590c-60cf-49ca-910a-1bd5940ce2c2/original/0",
                    "name": "Our Third Wave Coffee",
                    "url": "https://graphcommons.com/graphs/c7a0590c-60cf-49ca-910a-1bd5940ce2c2"
                }
            ],
            "hubs": [],
            "id": "70e9f5a9-8e97-022d-e285-5c0c52da7467",
            "image": "http://google.github.io/material-design-icons/maps/svg/ic_store_mall_directory_24px.svg",
            "name": "Blue Bottle Coffee",
            "nodetype": {
                "color": "#17A03F",
                "id": "741161fa-3836-41e1-0efd-67df26fb8831",
                "name": "Roastery"
            },
            "properties": {
                "Website": "https://bluebottlecoffee.com"
            },
            "reference": null,
            "status": 0,
            "url": "https://graphcommons.com/nodes/70e9f5a9-8e97-022d-e285-5c0c52da7467",
            "users": [
                {
                    "id": "db35b4cd-b260-40ee-b921-4c503d7f070a",
                    "image_url": "http://www.gravatar.com/avatar/2783268d0c97e51e5d18d39951d6ee57?default=https%3A%2F%2Fgraphcommons.com%2Fsystem%2Fusers%2Fmissing.png",
                    "url": "https://graphcommons.com/users/db35b4cd-b260-40ee-b921-4c503d7f070a",
                    "username": "dara"
                }
            ]
        }
    ]
}

This endpoint lets you search for nodes in Graph Commons. Currently, queries are searched against the name property of the nodes. Private nodes will return only if the user has access to them.

To limit the scope of the query to a specific hub or graph, supply the id of the graph or hub along with the query. See the parameters table below for more options.

HTTP Request

GET https://graphcommons.com/api/v1/nodes/search

URL Parameters

Parameter Description
query query to be searched
hub id of the hub to search in
graph id of the graph to search in
status status of the nodes to return.

Available values:
0 => published
1 => work in progress
2 => private
public => published and work in progress
limit limit the number of results (max: 20)
skip number of results to skip

GET hubs/:id

curl -XGET 'https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1'
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
    "description": "",
    "disclaimer": null,
    "edgetypes": [
        "25. DÖNEM MENSUBU",
        "25. DÖNEM TEMSİL ETTİ",
        "24. DÖNEM MENSUBU",
        "24. DÖNEM TEMSİL ETTİ",
        "23. DÖNEM MENSUBU",
        "23. DÖNEM TEMSİL ETTİ",
        "22. DÖNEM MENSUBU",
        "22. DÖNEM TEMSİL ETTİ",
        "21. DÖNEM MENSUBU",
        "21. DÖNEM TEMSİL ETTİ",
        "İNCELEDİ",
        "İMZALADI",
        "SUNULDUĞU DÖNEM",
        "MECLİSTE YER ALDI",
        "HİZMET DÖNEMİ",
        "20. DÖNEM MENSUBU",
        "20. DÖNEM TEMSİL ETTİ",
        "YÖNETİM KURULU BAŞKANI",
        "YÖNETİM KURULU ÜYESİ",
        "YÖNETİM KURULU BAĞIMSIZ ÜYESİ"
    ],
    "id": "2fa2394d-c6b1-4420-b842-760d10544ba1",
    "image": "https://graphcommons.com/system/hubs/images/2fa2394d-c6b1-4420-b842-760d10544ba1/original/tbmm.jpg?1437497383",
    "members": [
        {
            "id": "c06b79d9-a094-4bd7-9f48-f6c224cfe6e1",
            "image_url": "https://graphcommons.com/system/users/images/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1/original/burak-arikan.jpeg?1434186199",
            "url": "https://graphcommons.com/users/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1",
            "username": "arikan"
        },
        {
            "id": "d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
            "image_url": "https://graphcommons.com/system/users/images/d012995d-2e9b-43b9-a1a6-677fb4ef8f40/original/avatar.jpeg?1436996624",
            "url": "https://graphcommons.com/users/d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
            "username": "ahmetkizilay"
        }
    ],
    "name": "TBMM Haritaları",
    "nodes_count": 9541,
    "nodetypes": [
        "Komisyon",
        "Kanun Teklifi",
        "Dönem",
        "Siyasi Parti",
        "Şehir",
        "Şirket",
        "Millet Vekili"
    ],
    "owner": {
        "id": "d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
        "image_url": "https://graphcommons.com/system/users/images/d012995d-2e9b-43b9-a1a6-677fb4ef8f40/original/avatar.jpeg?1436996624",
        "url": "https://graphcommons.com/users/d012995d-2e9b-43b9-a1a6-677fb4ef8f40",
        "username": "ahmetkizilay"
    },
    "subtitle": "",
    "url": "https://graphcommons.com/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1",
    "website": ""
}

This endpoint gives an overview of the hubs. The nodes and edges in the hub are not returned from this endpoint.

HTTP Request

GET https://graphcommons.com/api/v1/hubs/:id

URL Parameters

Parameter Description
id the ID of the hub

GET hubs/:id/types

curl -XGET 'https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1/types'
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1/types") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
  "edgetypes": [
      "25. DÖNEM MENSUBU",
      "25. DÖNEM TEMSİL ETTİ",
      "24. DÖNEM MENSUBU",
      "24. DÖNEM TEMSİL ETTİ",
      "23. DÖNEM MENSUBU",
      "23. DÖNEM TEMSİL ETTİ",
      "22. DÖNEM MENSUBU",
      "22. DÖNEM TEMSİL ETTİ",
      "21. DÖNEM MENSUBU",
      "21. DÖNEM TEMSİL ETTİ",
      "İNCELEDİ",
      "İMZALADI",
      "SUNULDUĞU DÖNEM",
      "MECLİSTE YER ALDI",
      "HİZMET DÖNEMİ",
      "20. DÖNEM MENSUBU",
      "20. DÖNEM TEMSİL ETTİ",
      "YÖNETİM KURULU BAŞKANI",
      "YÖNETİM KURULU ÜYESİ",
      "YÖNETİM KURULU BAĞIMSIZ ÜYESİ"
  ],
  "id": "2fa2394d-c6b1-4420-b842-760d10544ba1",
  "name": "TBMM Haritaları",
  "nodetypes": [
      "Komisyon",
      "Kanun Teklifi",
      "Dönem",
      "Siyasi Parti",
      "Şehir",
      "Şirket",
      "Millet Vekili"
  ]
}

This endpoint gives a simple summary of all node types and edge types in a hub.

HTTP Request

GET https://graphcommons.com/api/v1/hubs/:id/types

URL Parameters

Parameter Description
id the ID of the hub

GET hubs/:id/paths

curl -XGET 'https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1/paths?from=e8875a6c-a64b-4852-9c92-5460dabb796a&to=6aabbbab-ac3d-4df9-acac-00fa6dade1eb&limit=1'
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/hubs/2fa2394d-c6b1-4420-b842-760d10544ba1/paths?from=e8875a6c-a64b-4852-9c92-5460dabb796a&to=6aabbbab-ac3d-4df9-acac-00fa6dade1eb&limit=1") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
    "edges": {
        "41d6eb21-27dd-4e4c-ad23-9ba753a0f5d8": {
            "color": "#f9c929",
            "directed": true,
            "edge_type": "24. DÖNEM TEMSİL ETTİ",
            "from": "e8875a6c-a64b-4852-9c92-5460dabb796a",
            "id": "41d6eb21-27dd-4e4c-ad23-9ba753a0f5d8",
            "obj": "Relation",
            "reference": null,
            "to": "922b2ac1-0f25-4194-92a2-7b339262d18e",
            "type_id": "adf365aa-5ae7-553a-93ee-bbb694e61278",
            "weight": "1"
        },
        "f1e6f18b-b3a2-4a79-b26e-0167e6097bec": {
            "color": "#f9c929",
            "directed": true,
            "edge_type": "24. DÖNEM TEMSİL ETTİ",
            "from": "6aabbbab-ac3d-4df9-acac-00fa6dade1eb",
            "id": "f1e6f18b-b3a2-4a79-b26e-0167e6097bec",
            "obj": "Relation",
            "reference": null,
            "to": "922b2ac1-0f25-4194-92a2-7b339262d18e",
            "type_id": "adf365aa-5ae7-553a-93ee-bbb694e61278",
            "weight": "1"
        }
    },
    "nodes": {
        "6aabbbab-ac3d-4df9-acac-00fa6dade1eb": {
            "created_at": 1437494603,
            "description": "Sırrı Süreyya Önder, 7 Temmuz 1962'de Adıyaman'da doğdu. Babasının adı Ziya, annesinin adı Zeliha'dır.      Film Yönetmeni ve Senarist; Adıyaman Lisesi mezunudur.      Siyasal Bilgiler Fakültesi 2. sınıfından ayrıldı. Sinema yönetmenliği ve senaristliği ile çeşitli gazetelerde köşe yazarlığı yaptı. Fakültelerde sinema dersleri verdi. Senaryosunu yazıp ve yönettiği 1 filmi, uyarlamasını yaptığı 1 filmi ve sadece senaryosunu yazdığı 1 filmi bulunmaktadır.      Önder, 1 çocuk babasıdır.",
            "id": "6aabbbab-ac3d-4df9-acac-00fa6dade1eb",
            "image": "https://www.tbmm.gov.tr/mv_resim/6963.jpg",
            "name": "Sırrı Süreyya ÖNDER 6963",
            "obj": "Node",
            "reference": "https://www.tbmm.gov.tr/develop/owa/milletvekillerimiz_sd.bilgi?p_donem=25&p_sicil=6963",
            "type": {
                "color": "#333333",
                "id": "22ac1ca2-a326-8634-0f3a-8bd82b00a079",
                "name": "Millet Vekili"
            },
            "updated_at": 1442046606,
            "url": "https://graphcommons.com/nodes/6aabbbab-ac3d-4df9-acac-00fa6dade1eb"
        },
        "922b2ac1-0f25-4194-92a2-7b339262d18e": {
            "created_at": 1437486819,
            "description": null,
            "id": "922b2ac1-0f25-4194-92a2-7b339262d18e",
            "image": null,
            "name": "İSTANBUL",
            "obj": "Node",
            "reference": null,
            "type": {
                "color": "#cba282",
                "id": "15d2f862-8c1c-205d-7c82-14c3600b4c70",
                "name": "Şehir"
            },
            "updated_at": 1439636142,
            "url": "https://graphcommons.com/nodes/922b2ac1-0f25-4194-92a2-7b339262d18e"
        },
        "e8875a6c-a64b-4852-9c92-5460dabb796a": {
            "created_at": 1437490193,
            "description": "Recep Tayyip Erdoğan, 26 Şubat 1954'te İstanbul'da doğdu. Babasının adı Ahmet, annesinin adı Tenzile'dir.      İktisatçı; Marmara Üniversitesi İktisadi ve İdari Bilimler Fakültesini bitirdi.      Özel sektörde müşavirlik ve üst düzey yöneticilik yaptı. İstanbul Büyükşehir Belediye Başkanlığı görevinde bulundu. Adalet ve Kalkınma Partisi Kurucular Kurulu Üyesi oldu ve Kurucu Genel Başkanı seçildi.      22. Dönemde Siirt, 23. Dönemde İstanbul Milletvekili seçildi. 59 ve 60. Hükümette Başbakanlık görevini yürüttü. 61. Hükümette üçüncü defa Başbakanlık görevini üstlendi.      İngilizce bilen Erdoğan, evli ve 4 çocuk babasıdır.",
            "id": "e8875a6c-a64b-4852-9c92-5460dabb796a",
            "image": "https://www.tbmm.gov.tr/mv_resim/6371.jpg",
            "name": "Recep Tayyip ERDOĞAN 6371",
            "obj": "Node",
            "reference": "https://www.tbmm.gov.tr/develop/owa/milletvekillerimiz_sd.bilgi?p_donem=24&p_sicil=6371",
            "type": {
                "color": "#333333",
                "id": "22ac1ca2-a326-8634-0f3a-8bd82b00a079",
                "name": "Millet Vekili"
            },
            "updated_at": 1442046620,
            "url": "https://graphcommons.com/nodes/e8875a6c-a64b-4852-9c92-5460dabb796a"
        }
    },
    "paths": [
        {
            "dirs": [
                "out",
                "in"
            ],
            "edges": [
                "41d6eb21-27dd-4e4c-ad23-9ba753a0f5d8",
                "f1e6f18b-b3a2-4a79-b26e-0167e6097bec"
            ],
            "nodes": [
                "e8875a6c-a64b-4852-9c92-5460dabb796a",
                "922b2ac1-0f25-4194-92a2-7b339262d18e",
                "6aabbbab-ac3d-4df9-acac-00fa6dade1eb"
            ],
            "path_string": "(Recep Tayyip ERDOĞAN 6371) - [24. DÖNEM TEMSİL ETTİ] -> (İSTANBUL) <- [24. DÖNEM TEMSİL ETTİ] - (Sırrı Süreyya ÖNDER 6963)"
        }
    ]
}

This endpoint returns paths between nodes inside a hub. See the detailed path documentation below.

HTTP Request

GET https://graphcommons.com/api/v1/hubs/:id/paths

URL Parameters

Parameter Description
ID The ID of the hub
from the ID of the node to start from
to the ID of the node to end at
fromtype the node type to start from
totype the node type to end at
via the list of accepted edge types for paths
strict set to true to force paths to match via pattern exactly
depth max depth for paths
not ensure start and end nodes are not connected by the specified edge type
limit number of paths to return
skip number of paths to skip

GET hubs/:id/collab_filter

curl -XGET "https://graphcommons.com/api/v1/hubs/19dba76e-9aa4-4abe-9502-93525bceae7d/collab_filter?from=a048e14a-ef31-49c9-a937-4b499b91caa1&via=MEMBER_OF"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_delete("https://graphcommons.com/api/v1/hubs/19dba76e-9aa4-4abe-9502-93525bceae7d/collab_filter?from=a048e14a-ef31-49c9-a937-4b499b91caa1&via=MEMBER_OF") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

{
  "suggestions": [
    {
      "node": {
        "created_at": 1452107498,
        "description": "",
        "id": "085d790a-577f-4006-b3c9-276cd5824664",
        "image": "",
        "name": "ifadeozgurlugu",
        "obj": "Node",
        "properties": {
          "channel_id": "C0AHKBJ06"
        },
        "reference": "",
        "type": {
          "color": "#8c564b",
          "id": "ce6afe52-b87a-460c-8db3-e3c94be5c99a",
          "name": "Channel"
        },
        "updated_at": 1452107498,
        "url": "https://graphcommons.com/nodes/085d790a-577f-4006-b3c9-276cd5824664"
      },
      "path_count": 42,
      "probability": 0.22459893048128343
    },
    {
      "node": {
        "created_at": 1452107498,
        "description": "",
        "id": "d8d9de40-6ba2-4e7d-b692-532a5933c0fd",
        "image": "",
        "name": "egitim",
        "obj": "Node",
        "properties": {
          "channel_id": "C0AHUQEBC"
        },
        "reference": "",
        "type": {
          "color": "#8c564b",
          "id": "ce6afe52-b87a-460c-8db3-e3c94be5c99a",
          "name": "Channel"
        },
        "updated_at": 1452107498,
        "url": "https://graphcommons.com/nodes/d8d9de40-6ba2-4e7d-b692-532a5933c0fd"
      },
      "path_count": 34,
      "probability": 0.18181818181818182
    }
  ]
}

This endpoint suggests edges for a given node, based on the number of shared neighbors with other nodes in the hub. This endpoint can be used for the classical recommendation case, such as, what other books are purchased by people who purchased the same book as I did. See the detailed path documentation below.

HTTP Request

GET https://graphcommons.com/api/v1/hubs/:id/collab_filter

URL Parameters

Parameter Description
ID The ID of the hub
from the ID of the node to get suggestions for
via the edge type for which the suggestions will be calculated
among the edge type pattern to specify the group of nodes to compare common neighbors.

GET hubs/:id/graphs

In order to query nodes for a hub use /graphs/search endpoint with hub parameter.

GET hubs/:id/nodes

In order to query nodes for a hub use /nodes/search endpoint with hub parameter.

curl -XGET "https://graphcommons.com/api/v1/search?query=penal&limit=4"
  -H "Authentication: <YOUR_API_KEY>"
require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/search?query=penal&limit=5") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end
c.on_body { |data| print(data) }
c.perform
# TO BE ADDED

Example response

[
   {
      "obj":"Node",
      "id":"a2d88847-994f-4e61-b525-532a47a7a9c1",
      "name":"Death penalty",
      "description":null,
      "image":null,
      "reference":null,
      "created_at":1441633018,
      "updated_at":1441633018,
      "url":"https://graphcommons.com/nodes/a2d88847-994f-4e61-b525-532a47a7a9c1",
      "graphs_count":1,
      "type":{
         "id":"a4b3d358-0d1f-5777-22be-f9b48ce6b386",
         "name":"Penalty",
         "color":"#db4165"
      },
      "graphs":[
         {
            "id":"fa5258ea-72f3-4c6c-9bac-9b8f4c21c788",
            "name":"ss",
            "image_url":"https://graphcommons.com/system/graphs/images/fa5258ea-72f3-4c6c-9bac-9b8f4c21c788/original/",
            "url":"https://graphcommons.com/graphs/fa5258ea-72f3-4c6c-9bac-9b8f4c21c788"
         }
      ],
      "hubs":[

      ],
      "users":[
         {
            "id":"c06b79d9-a094-4bd7-9f48-f6c224cfe6e1",
            "username":"arikan",
            "image_url":"https://graphcommons.com/system/users/images/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1/original/burak-arikan.jpeg",
            "url":"https://graphcommons.com/users/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1"
         }
      ]
   },
   {
      "obj":"Graph",
      "id":"3dcbbda0-1843-4d24-b891-c5be13dd935c",
      "name":"Penal Systems Network",
      "subtitle":"Network map of world's penal systems that evoke controversy",
      "description":"A network map of world countries connected to juridical topics whether or not they are being exercised and how they are being exercised such as life imprisonment, parole, indefinite sentence, and amnesty. This network map provides a comparison of penalties at scale between countries and legal systems. For example, life imprisonment does not exist in Norway, and in many of the South American countries. Indefinite sentence is a big issue in Turkey and Middle East, but not in Europe.\r\n\u003cbr\u003e\u003cbr\u003e\r\nThe network map is a self-organizing software system, where the layout is organized based on the connections, showing both similarities and differences between countries, central penalties, and peripheral penalties.\r\n\u003cbr\u003e \u003cbr\u003e\r\nThis work was first shown in Henie-Onstad Kunstsenter, Oslo \"We Are Living On a Star\" exhibition January 30th – April 27th 2014.",
      "status":1,
      "status_text":"Published",
      "image_url":"https://graphcommons.com/system/graphs/images/3dcbbda0-1843-4d24-b891-c5be13dd935c/original/worlds-penal-systems.jpg",
      "nodes_count":136,
      "created_at":1415816246,
      "updated_at":1451921907,
      "owner":{
         "id":"c06b79d9-a094-4bd7-9f48-f6c224cfe6e1",
         "username":"arikan",
         "image_url":"https://graphcommons.com/system/users/images/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1/original/burak-arikan.jpeg",
         "url":"https://graphcommons.com/users/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1"
      },
      "hubs":[

      ]
   },
   {
      "obj":"User",
      "id":"233f9863-bd66-4b0f-afc0-b161ea68aebb",
      "username":"erenalpbyktpc",
      "url":"https://graphcommons.com/users/233f9863-bd66-4b0f-afc0-b161ea68aebb",
      "image_url":"http://www.gravatar.com/avatar/bff83f55bfb22c145b09fb6834d4ae37?default=https%3A%2F%2Fgraphcommons.com%2Fsystem%2Fusers%2Fmissing.png",
      "graphs":[
         {
            "id":"e99eff7c-58dc-4400-8024-71e2765115c4",
            "name":"Komedi Dizileri Oyuncu İlişkileri",
            "image_url":"https://graphcommons.com/system/graphs/images/e99eff7c-58dc-4400-8024-71e2765115c4/original/e99eff7c-58dc-4400-8024-71e2765115c4.png",
            "url":"https://graphcommons.com/graphs/e99eff7c-58dc-4400-8024-71e2765115c4"
         },
         {
            "id":"1ff39935-91fa-437d-9b54-2cfe864473c8",
            "name":"teşvikiye-ıhlamurdere aksı caddelerinin kullanım amaçları",
            "image_url":"https://graphcommons.com/system/graphs/images/1ff39935-91fa-437d-9b54-2cfe864473c8/original/1ff39935-91fa-437d-9b54-2cfe864473c8.png",
            "url":"https://graphcommons.com/graphs/1ff39935-91fa-437d-9b54-2cfe864473c8"
         }
      ],
      "graphs_owned":2,
      "graphs_edited":2,
      "fullname":"Erenalp Büyüktopcu"
   }
]

This endpoint lets you search for Nodes, Graphs and Users in Graph Commons. The query keyword is checked against the name, description, and in the case of Graphs, subtitle properties. Private nodes and graphs will return only if the user has access to them.

HTTP Request

GET https://graphcommons.com/api/v1/search

URL Parameters

Parameter Description
query query to be searched
limit limit the number of results (max: 20)
skip number of results to skip

Signaling

Changes to the nodes and edges of a graph are carried out by a series of commands called signals in the request body. With these signals you can add, update or delete nodes, edges, node types and edge types.

All signals define an action key which specifies the type of signal. Below is the list of signal types that are supported by the Graph Commons API.

node_create

Example node_create signal

{
  "action": "node_create",
  "type": "Company",
  "name": "Facebook",
  "description": "Founded in 2002, it is the largest social networing website in the world",
  "properties": {
    "num_users": "1 billion",
    "year_founded": 2002
  }
}

This signal type is used for creating nodes. All signals of this type must define a type and name key. type - name pairs must be unique.

Upon saving this signal, a new node id is created. The type of the node is matched with a predefined node type from the hub/graph. If the node type does not already exist, a node type is created.

Required fields

Parameter Description Type
name name of the node String
type type of the node String

Optional fields

Parameter Description Type
description description of the node String
image url path for the image for the node String
reference url for a reference source for the node String
properties custom properties for the node Hash

edge_create

Example edge_create signal

{
  "action": "edge_create",
  "from_name": "Yahoo",
  "from_type": "Company",
  "name": "ACQUIRED",
  "to_name": "Tumblr",
  "to_type": "Company",
  "properties": {
    "cost": "$1b",
    "year_of_acquisition": 2013
  }
}

This signal type is used for creating edges. Source and target nodes for the edge will be created if they don’t already exist. Only one instance of edgetype is allowed between the same nodes. However, there could be multiple edges between the same node pair, as long as the their edge types are different.

Upon saving this signal a new edge id is created. The type of the edge is matched with a predefined edge type from the hub/graph. If the edge type does not already exist, a new edge type is created.

Required fields

Parameter Description Type
from_type type of source node String
from_name name of source node String
to_type type of target node String
to_name name of target node String
name type of the edge String

Optional fields

Parameter Description Type
Weight weight of the edge String
reference url for a reliable source for the edge String
properties custom properties for the node Hash

node_delete

Example node_delete signal

{
  "action": "node_delete",
  "id": "48f07709-e5aa-44b5-80d9-0a92cc238183"
}

This signal type is used for deleting nodes.

Required fields

Parameter Description Type
id id of the node to be deleted String

edge_delete

Example edge_delete signal

{
  "action": "edge_delete",
  "id": "48f07709-e5aa-44b5-80d9-0a92cc238183",
  "from": "1c9e0d69-b26a-4d0e-9e3a-7149aa4a636e",
  "to": "91cae6e7-0657-4c2b-b6e7-9333c46e060e",
  "name": "FRIENDS_WITH"
}

This signal type is used for deleting edges.

Required fields

Parameter Description Type
id id of the edge to be deleted String
from id of the source node of the edge String
to id of the target node of the edge String
name type of the edge String

node_update

Example node_update signal

{
  "action": "node_update",
  "id": "48f07709-e5aa-44b5-80d9-0a92cc238183",
  "description": "New description",
  "properties": {
    "age": "22"
  },
  "prev": {
    "description": "old description",
    "properties": {
      "age": "21"
    }
  }
}

This signal type is used for updating a signal. All fields except for id will be updated in the node.

Required fields

Parameter Description Type
id id of the node to be updated String

Optional fields

Parameter Description Type
name new name for the node String
type_id new nodetype id for the node String
description new description for the node String
image new image for the node String
reference new reference for the node String
properties new custom property values for the node Hash
prev a hash that holds the previous values for the node Hash

edge_update

Example edge_update signal

{
  "action": "edge_update",
  "id": "48f07709-e5aa-44b5-80d9-0a92cc238183",
  "from": "1c9e0d69-b26a-4d0e-9e3a-7149aa4a636e",
  "to": "91cae6e7-0657-4c2b-b6e7-9333c46e060e",
  "weight": 8,
  "prev": {
    "weight": 2
  }
}

Required fields

Parameter Description Type
id id of the edge to be updated String
from id of source node String
to id of target node String

Optional fields

Parameter Description Type
weight weight of the relation Integer
reference new reference for the relation String
properties new custom property values for the relation Hash
prev a hash that holds the previous values for the relation Hash

nodetype_update

TBA

edgetype_update

TBA

nodetype_delete

TBA

edgetype_delete

TBA

Appendix

Paths Endpoint Details

This part elaborates on the graphs/:id/paths and hubs/:id/paths endpoints. Examples in this section are given for graphs, however they apply to hubs as well.

Path between two specific nodes

To find any path between two specified nodes, set to and from parameters to nodes ids.

https://graphcommons.com/ap1/v1/graphs/GRAPH-ID/paths?from=START-NODE-ID&to=END-NODE-ID

Path from a specific node to any node of type

To find paths from a specific node, set from parameter. To specify destination node type set totype to the nodetype of the node.

https://graphcommons.com/ap1/v1/graphs/GRAPH-ID/paths?from=START-NODE-ID&totype=Person

Specify edgetypes for the path

By default any edge type in a graph will be traversed to find a path. To limit the traversal to specific edge types use via parameter. For example, find only paths containing FRIENDS_WITH and HATES:

https://graphcommons.com/ap1/v1/graphs/GRAPH-ID/paths?from=START-NODE-ID&to=END-NODE-ID&via=FRIENDS_WITH,HATES

Specify strict paths

Use strict=true to specify exact steps along the path. For example, to find people my friends hate, you can use the following query

https://graphcommons.com/ap1/v1/graphs/GRAPH-ID/paths?from=FROM-NODE-ID&totype=person&via=FRIENDS_WITH,HATES&strict=true

Specifying variable length strict paths

To have more control over the path, you can specify cypher-like variable length in via parts. For variable length depth, *min..max, for exact length *num can be added to each edgetypes in via.

For example, to get messages your friends or friends of friends wrote, you can use a query like this:

https://graphcommons.com/ap1/v1/graphs/GRAPH-ID/paths?from=MY-NODE-ID&totype=Message&via=FRIENDS_WITH*1..2,WROTE&strict=true

Specifying not parameter

Adding not parameter allows you to ensure that the start and end nodes of the path are not neighbors.

Use not=<EDGETYPE-NAME> to make sure that start and end nodes of existing paths are not connected by the specified edge type. Use not=* to ensure that there are no edges of any type between start and end nodes.

To find movies your friends saw but you did not you can use a query like this: https://graphcommons.com/api/v1/graphs/GRAPH-ID/paths?from=MY-NODE-ID&totype=Movie&via=FRIENDS_WITH,SEEN&not=SEEN&strict=true

Collab filter endpoint details

This part elaborates on the graphs/:id/collab_filter and hubs/:id/collab_filter endpoints. Examples in this section are given for graphs, however they apply to hubs as well.

This endpoint takes a starting node with from parameter and suggests edges for the starting node based its shared neighbors with other nodes.

Get suggestions based on the edge type

via parameter sets the edge type on which the suggestion will be based. To get movies I haven’t seen but seen by people who have seen the same movies as I did, I can use the following query:

https://graphcommons.com/api/v1/graphs/GRAPH-ID/collab_filter?from=MY-NODE-ID&via=SEEN

Specifying nodes on which suggestions are based

All nodes that share a neighbor connected by the edge type specified in via are considered for suggestions. It is possible to limit this group of nodes with among parameter and only consider nodes that have a certain relation to the source node.

For example, using among=FRIENDS_WITH, I can get suggestions based on friends who watched the same movies as I did:

https://graphcommons.com/api/v1/graphs/GRAPH-ID/collab_filter?from=MY-NODE-ID&via=SEEN&via=FRIENDS_WITH

It is also possible to specify a path with among parameter. For example, to get suggestions based on people who liked the same movies as I did, I can use:

https://graphcommons.com/api/v1/graphs/GRAPH-ID/collab_filter?from=MY-NODE-ID&via=SEEN&via=LIKED,LIKED

Destination node type

In cases when there are more than one type of nodes using the same edge type, it is possible to specify the exact node type to get suggestions for. For example, if my network contains Plays in addition to Movies, I can add totype=Movie to my query to get suggestions for Movies only.

https://graphcommons.com/api/v1/graphs/GRAPH-ID/collab_filter?from=MY-NODE-ID&via=SEEN&via=LIKED,LIKED&totype=Movie

Libraries & Examples

Graph Commons API wrapper libraries in Ruby, Python, PHP, Node.js:

Applications using the Graph Commons API:

Errors

Some error codes used by Graph Commons API:

Error Code Meaning
400 Bad Request –
401 Unauthorized –
403 Forbidden –
404 Not Found –
405 Method Not Allowed –
406 Not Acceptable –
410 Gone –
429 Too Many Requests –
500 Internal Server Error –
503 Service Unavailable –