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.

PUT graphs/:id/clear

curl -XPUT "https://graphcommons.com/api/v1/graphs/19dba76e-9aa4-4abe-9502-93525bceae7d/clear"
  -H "Authentication: <YOUR_API_KEY>"

require 'curl'

c = Curl::Easy.http_put("https://graphcommons.com/api/v1/graphs/19dba76e-9aa4-4abe-9502-93525bceae7d/clear") do |curl|
  curl.headers['Content-Type'] = 'application/json'
  curl.headers['Authentication'] = '<YOUR_API_KEY>'
end

# TO BE ADDED

This endpoint clears all data (nodes and edges) of a given graph. In this case, the graph is not deleted, so it can be updated with new data using the graph id. A typical use case could be to embed the graph to a web page and update it programmatically.

HTTP Request

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

URL Parameters

Parameter	Description
id	the ID of the graph

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.

GET graphs/search

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/e14dd81a-56ab-800c-f0b6-d2a9f4264722
  -H "Authentication: <YOUR_API_KEY>"

require 'curl'

c = Curl::Easy.http_get("https://graphcommons.com/api/v1/nodes/e14dd81a-56ab-800c-f0b6-d2a9f4264722") 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('e14dd81a-56ab-800c-f0b6-d2a9f4264722'))

Example response

{
  "node": {
    "id": "e14dd81a-56ab-800c-f0b6-d2a9f4264722",
    "name": "Public Seminar",
    "description": null,
    "image": "http://www.publicseminar.org/wp-content/uploads/2013/12/public_seminar1.png",
    "reference": null,
    "created_at": "2014-10-23T01:54:46.000+00:00",
    "updated_at": "2015-06-23T14:04:04.000+00:00",
    "url": "https://graphcommons.com/nodes/e14dd81a-56ab-800c-f0b6-d2a9f4264722",
    "graphs_count": 1,
    "type": {
      "id": "9f9e90e6-dda7-75ad-cf5a-a7e978199f4a",
      "name": "Project",
      "color": "#56c8ec"
    },
    "graphs": [
      {
        "id": "1a93e8fa-e3ce-4ec7-ba16-814b867d1bcb",
        "name": "Graph Commons Dev Community",
        "image_url": "https://d3cnky5llnzyoo.cloudfront.net/graphs/images/1a93e8fa-e3ce-4ec7-ba16-814b867d1bcb/original/d4da2b97-5c5f-4bf5-9fdd-7bea363779db_1.png",
        "url": "https://graphcommons.com/graphs/1a93e8fa-e3ce-4ec7-ba16-814b867d1bcb"
      }
    ],
    "hubs": [],
    "users": [
      {
        "id": "c06b79d9-a094-4bd7-9f48-f6c224cfe6e1",
        "username": "arikan",
        "image_url": "https://d3cnky5llnzyoo.cloudfront.net/users/images/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1/original/burak-arikan.jpeg",
        "url": "https://graphcommons.com/users/c06b79d9-a094-4bd7-9f48-f6c224cfe6e1"
      }
    ],
    "edge_types": [
      "MEMBER"
    ],
    "edges": [
      {
        "type": "MEMBER",
        "weight": "1",
        "direction": "out",
        "graph_ids": null,
        "node": {
          "id": "0547f608-7280-2719-df66-fa8c01555a11",
          "url": "https://graphcommons.com/nodes/0547f608-7280-2719-df66-fa8c01555a11",
          "name": "The New School for Social Research",
          "status": 1,
          "type": {
            "id": "cf15870e-480b-7ed3-a709-ecc588371fdb",
            "name": "Organization",
            "color": "#297de3"
          }
        }
      },
      {
        "type": "MEMBER",
        "weight": "1",
        "direction": "in",
        "graph_ids": null,
        "node": {
          "id": "cf0e5d9b-ae76-eecf-1613-e4c97550e31a",
          "url": "https://graphcommons.com/nodes/cf0e5d9b-ae76-eecf-1613-e4c97550e31a",
          "name": "Zeyno Ustun",
          "status": 1,
          "type": {
            "id": "2a6d5dbb-6caf-d171-d11e-c8c36131a28b",
            "name": "Person",
            "color": "#4d504e"
          }
        }
      }
    ]
  }
}

This endpoint retrieves a node, all its properties, and edges.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the node to retrieve

GET nodes/search

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.

GET search

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

Given a snapshot of a network, can we infer which new interactions among its members are likely to occur in the near future? This question is formalized as the “link prediction” problem (See also link prediction in complex networks). Link prediction can be generated based on measures for analyzing the “proximity” of nodes in a network. Commonly, this method is also called “collaborative filtering” in the social networks field.

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:

• Ruby Wrapper initiated by Yakup Cetinkaya
• Node.js Wrapper initiated by Igal Nassima
• PHP Wrapper initiated by Kerem Güneş
• Python Wrapper initiated by Fatih Erikli

Applications using the Graph Commons API:

• Wordpress Plugin for Graph Commons initiated by Cenk Dölek
• Node.js Slack-to-GraphCommons initiated by Ahmet Kızılay
• Node.js Linkedin-to-GraphCommons initiated by Ahmet Kızılay
• Metagraph initiated by Yakup Cetinkaya
• .NET Graph Commons Excel Lab initiated by Batı Erk Yılmaz
• Ruby Instagram-to-GraphCommons initiated by Ahmet Kızılay

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 –