Using the API

Justin Zhen,
Co-Founder of KgBase

Formats

All endpoints use JSON format for both request payloads and for responses. Request should include header Content-Type with value application/json; charset=utf-8

Querying data

Getting all nodes

To get all nodes in the graph, use the query endpoint with empty JSON object as POST body.

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{}

Getting all nodes from specific tables

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{
  "labels": ["<TABLE ID>", "<TABLE ID>", ...]
}
  • <TABLE ID> - ID of the table

Using pagination to sort nodes

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{
  "pagination": {
    "label": "<TABLE ID>",
    "offset": 0,
    "limit": 100,
    "sort_column": "<SORT COLUMN ID>",
    "sort_direction": "<SORT DIRECTION>"
  }
}
  • <TABLE ID> - Table to be used for pagination. Only nodes from this table will be returned.
  • <SORT COLUMN ID> - Column to sort by
  • <SORT DIRECTION> - Sort direction. asc or desc.

Finding nodes related to set of starting nodes

If you have a set of existing nodes, you can use the query endpoint to find all nodes connected to your initial set.

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{
  "starting_vertices": ["<VERTEX ID>", "<VERTEX ID>", ...]
}
  • <VERTEX ID> - Array of vertex IDs to be used as starting points for the query.

Filtering nodes

In any use case, you can add an array of filters, to return only nodes that match it.

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{
  "filters": [{
    "label": "<TABLE ID>",
    "property": "<COLUMN ID>",
    "predicate": "<PREDICATE>",
    "value": "<VALUE>",
  }, ...]
}
  • <TABLE ID> - You have to pick a table in order to filter. Filtering through all nodes from all tables is currently not possible.
  • <COLUMN ID> - Column for filtering
  • <PREDICATE> - Filter predicate. Possible predicates: =, >, >=, <, <=, !=
  • <VALUE> - Value for filter. String or number.

Grouping and aggregation

It's possible to use groups and aggregations, to generate summarized data from the results of your query.

POST https://kgbase.com/api/<USERNAME>/<PROJECT ID>/query
{
  "summary": {
    "label": "<TABLE ID>",
        "groups": [{
      "property": "<GROUP COLUMN ID>"
    }],
    "aggregations": [{
      "property": "<AGGREGATION COLUMN ID>",
      "function": "<FUNCTION NAME>"
    }]
  }
}
  • <TABLE ID> - table in which you wanna perform the aggregation
  • <GROUP COLUMN ID> - column to group by
  • <AGGREGATION COLUMN ID> - column on which to perform the aggregation
    • This is different from group column, because you could group by one column, such as gender, and then aggregate values from another column, such as height
  • <FUNCTION NAME> - aggregation function to be used.
    • Possible values: count, mean, max, min, sum

Modifying data

We're still working on API endpoints to modify data, and the documentation will be available soon.

Show us some love

Do you find our product interesting?
Show us your support!