Develop

Integrate your own applications and scripts with the Knowledge Graph
Getting programmatic access

How to request programmatic access to the HBP Knowledge Graph

HBP KG provides convenient tools and APIs for your application or your script! To be able to access the KG programmatically, all you need is:

After you have registered (and with that accepted the terms of use for programmatic access), you will receive the credentials to get access to the public APIs of the HBP Knowledge Graph.
Please be aware that - depending on your access permissions - you might not be able to query all meta-data the Knowledge Graph contains. If you need access to additional resources, you need to request those by providing the reason for why you need the additional access. Please also note, that additional rules and terms of use can apply for extended access.

The Query API

The Knowledge Graph Query API

The documentation of the publicly available Knowledge Graph API which is meant for the external community can be found here and is subject to regular extension and improvement. If you are missing some functionality, do not hesitate to contact us

Authentication and authorization

Most of the endpoints (and definitively all which provide you with real meta-data) are only accessible in an authenticated manner. You will need to pass a bearer token in the "Authorization" header. To get an authorization token, you need to access the authorization endpoint, log in with your HBP account (initially give the application access) and to re-use the shown token. Please note, that this token times out after some time. If you need an automatic refresh of your token (e.g. for regular server-2-server communication), please contact us.

A "hello world" query

A query for the Knowledge Graph is defined declaratively in JSON-LD (see example below) and always executed against a specific data structure (e.g. a "Dataset") allowing to traverse the graph if required. For your convenience, we provide a graphical UI to build simple queries (compare Search data - KG Query).

{
  "@context": {
    "@vocab": "https://schema.hbp.eu/graphQuery/",
    "query": "https://schema.hbp.eu/myQuery/",
    "fieldname": {
      "@id": "fieldname",
      "@type": "@id"
    },
    "relative_path": {
      "@id": "relative_path",
      "@type": "@id"
    }
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:myContributors",
      "relative_path": "https://schema.hbp.eu/minds/contributors"
      "fields": [
        {
          "fieldname": "query:myContributorName",
          "relative_path": "http://schema.org/name"
        }
      ]
    }
  ]
}
A "hello world" of a KG Query looking for the name of an object (e.g. a dataset) as well as the names of its contributors

The @context defines the semantical context for the query (the query-internal properties belong to the namespace https://schema.hbp.eu/graphQuery/). Please note, that you can specify the fields depending on the data structure in the Knowledge Graph by defining the relative path. By specifying a "fieldname", the results will be renamed to your definition.
You can test your query by using the provided endpoint. Please note, that this endpoint is for testing only and should not be used for productive use (we might restrict the endpoint at some moment in time).

According to the rules of JSON-LD and the "relative_path" definition, the above relative paths are short writings. "relative_path": "https://schema.hbp.eu/minds/contributors" is a short form of writing "relative_path": {"@id": "https://schema.hbp.eu/minds/contributors"}. Please note, that in the HBP Knowledge Graph, connections are always directed. In this example, the dataset contains the links to its contributors what makes this connection "outgoing". Let's imagine that the contributors would contain the connection to the dataset as part of a property "https://schema.hbp.eu/minds/datasets" and this becomes an "incoming" connection for the dataset. In this case we would need to "reverse" the connection which we could do by simply defining "relative_path": {"@id": "https://schem.hbp.eu/minds/datasets", "reverse": true}. BTW: The KG Query Builder will do this automatically for you.

Store your query

To make productive use of your query, please upload your query specification to the Knowledge Graph. You can specify your own queryId. If the queryId hasn't been taken by anybody else, the upload will be successful and you can make use of your stored query with the comfortable GET-endpoint. If you "own" the specification stored with a queryId, you can always update (by re-uploading) or delete it. Please note, that if you have deleted a query, its id can be re-used by somebody else again.
By storing your query in the Knowledge Graph, you not only profit from various simplifications, but you e.g. also can auto-generate python code to interact with python objects (incl. linting support) instead of the REST API directly.

Restructure your data with the query API

The query API not only allows you to comfortably specify in which fields you're interested in and define new names for those fields, but you also can restructure the resulting elements:

Flatten

If you traverse the graph (e.g. when we asked for the contributors in the first example) and are not interested in the intermediate objects (the contributors) but only in the "leaf" fields (the contributor's names), you can flatten them (also supported by the UI).

{
  "@context": {
    ...
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:contributors",
      "relative_path": [
        "https://schema.hbp.eu/minds/contributors",
        "http://schema.org/name"
      ]
    }
  ]
}
"Flattened" contributor names - by specifying an array of "relative_path"s, the result will be collected and "query:contributors" is now an array of strings instead of JSON objects containing a "query:myContributorsName"

Merge

If you have the need to collect information from multiple places into a single field, you can make use of the "merge" feature. You simply collect the different "relative_path"s to an array and wrap them into a "merge" field.

{
  "@context": {
    ...
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:everybodyInvolved",
      "merge": [
        {
          "relative_path": [
            "https://schema.hbp.eu/minds/custodians",
            "http://schema.org/name"
          ]
        },
        {
          "relative_path": [
            "https://schema.hbp.eu/minds/contributors",
            "http://schema.org/name"
          ]
        }
      ]
    }
  ]
}
The merge-mechanism: We collect all names of custodians as well as contributors into a field called "query:everybodyInvolved".

Restrict the results

Most of the times, you have specific criterias which have to be fulfilled by the resulting instances. You have different possibilities to specify them in the KG Query:

Required

Sometimes, you are only interested in results which actually have values for certain field. This can easily be achieved by declaring a "required" filter:

{
  "@context": {
    ...
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:contributors",
      "relative_path": [
        "https://schema.hbp.eu/minds/contributors",
        "http://schema.org/name"
      ],
      "required": true
    }
  ]
}
By specifying a "required" field, only objects which contain at least one contributor with a name are returned.

Filters (not supported by UI yet)

Additional filters can be applied for further restriction of the result.
Field filters can be applied to any field. The system currently knows the following filtering possibilities:

  • STARTS_WITH: The value of the field is validated to start with the given value WITHOUT wildcards (e.g. filter is "foo", "foobar" is returned, "barfoo" is not)
  • ENDS_WITH: The value of the field is validated to end with the given value WITHOUT wildcards (e.g. filter is "foo", "barfoo" is returned, "foobar" is not)
  • CONTAINS: The value of the field contains the given value WITHOUT wildcards (e.g. filter is "ooba", "foobar" is returned, "barfoo" is not)
  • EQUALS: The value of the field matches the given value (e.g. filter is "foobar", "foobar" is returned, "barfoo" is not)
  • REGEX: The value of the field matches the given regular expression (e.g. filter is "fo.*ar", "foobar" is returned, "barfoo" is not). Obviously, you could achieve all the filters above with regex as well. For performance reasons, we nevertheless suggest to use REGEX for complex filters only - if your case matches one of the above, you may rather use those.

Filters can either be defined statically (hard-coded), dynamically (parametrized) or both (fallback). Static filters contain the filter-value as part of the query ("value"). You also can declare a "parameter" providing the label of the query parameter for this filter. If you do so, you can execute the GET-endpoint with your additional parameters. To check which parameters are available for a stored query, please use this endpoint. If you specify a dynamic filter and the parameter is not set, the filter will be ignored.
If you have specified both ("value" and "parameter"), you have defined a "fallback" filter. Here, the filter-value can be overridden by defining it by query parameter. If the query parameter is not defined, the static declaration is used.
{
  "@context": {
    ...
  },
  "fields": [

    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:contributors",
      "relative_path": [
        "https://schema.hbp.eu/minds/contributors",
        "http://schema.org/name"
      ],
      "filter": {
        "op": "starts_with",
        "parameter": "contributorName",
        "value": "An"
      }
    }
  ]
}
A query with a field filter: You can either invoke the GET-endpoint with the additional parameter ?contributorName=Bo (so all contributors with a name starting with "Bo" will be returned - such as "Bob") or (if you don't specify the contributorName), all contributors with a name starting with "An" such as "Anna" would be returned.

In addition to the field filters, the system also knows instance filters (currently spatial search only). Instance filters are reducing the involved instances by a specific criteria and can be either located at the root of the specification or inside graph traversals on the instance level.
  • MBB: The "minimal bounding box" filter once specified restricts the returned instances to those which are spatially intersecting the given, 3-dimensional cube.
{
  "@context": {
    ...
  },
  "filter": {
    "op": "mbb",
    "parameter": "myBoundingBox",
    "value": "someReferenceSpace: [[120,270,300],[150,300,320]]"
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:myContributors",
      "relative_path": "https://schema.hbp.eu/minds/contributors"
      "fields": [
        {
          "fieldname": "query:myContributorName",
          "relative_path": "http://schema.org/name"
        }
      ]
    }
  ]
                    }
A minimal bounding box instance filter. We are only asking for instances which are located inside the bounding box either specified in the parameter "myBoundingBox" or in the statically assigned box. A minimal bounding box always consists of the referenceSpace declaration and two three-dimensional coordinates defining the boundaries of the box. You can lookup which parameters can be set and how they should be defined here.
Another spot to define an "instance filter" would have been at the level of "query:myContributors" - since here, we could restrict the contributors by further criterias (although the spatial search itself doesn't make so much sense for persons).

Order your results (not supported by UI yet)

By default, (although consistent over multiple queries) you can't be sure in which exact order the results are provided. This is the default behavior, because sorting always means performance loss which we want to avoid if not absolutely necessary. Sometimes, it is important to ensure a specific order though. We therefore provide two mechanisms for ordering:

Sort

If you wish to sort your instances alphabetically, you can do so by specifying the "sort" field. Currently, we only support the ascending order.

{
  "@context": {
    ...
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:contributors",
      "relative_path": [
        "https://schema.hbp.eu/minds/contributors",
        "http://schema.org/name"
      ],
      "sort": true
    }
  ]
}
Sorting the contributor names in alphabetical, ascending order
Ensure original order

If the original order shall be ensured (the order how it has been specified in the data sources), you can make use of this feature. One of the most obvious use-cases is the order of contributors, since the position has a specific meaning (it has e.g. a different meaning if you're first or last author)

{
  "@context": {
    ...
  },
  "fields": [
    {
      "fieldname": "query:myName",
      "relative_path": "http://schema.org/name"
    },
    {
      "fieldname": "query:contributors",
      "relative_path": [
        "https://schema.hbp.eu/minds/contributors",
        "http://schema.org/name"
      ],
      "ensure_order": true
    }
  ]
}
Setting the flag "ensure_order" enforces the order how it has been specified in the meta-data database.
The Nexus API

Write to the Knowledge Graph

The HBP Knowledge Graph bases on the underlying technology Nexus (currently in v0). It is therefore possible to make use of the Nexus API for updating and managing data programmatically.

To allow a manageable and well structured data-management, the HBP Knowledge Graph ensures the separation of the original data based on their sources. This means, that although multiple data sources are contributing to the overall "knowledge", each system stores its information in different areas. The inbuilt inference mechanism then takes care of the combination and aggregation of the "overall" knowledge (learn more).
Therefore, if you would like to insert / update / delete data via the Nexus API, you need access to your own, client specific space which you can request. We recommend to create a technical account for the programmatic access and to only request write access for this one.

Please note, that the contributed information is only accessible by the registered account (or other, read-only accounts registered for your client) by both, the Nexus API as well as the KG Query API. To make your meta-data accessible to the public (e.g. for other users of the KG Query API / the Search UI), it needs to pass a curation process which assures the compliance with the standards of HBP.

The Nexus API endpoint for the HBP Knowledge Graph can be found at https://nexus.humanbrainproject.org/. You will also get access to our integration environment located at https://nexus-int.humanbrainproject.org/, which is reset every day and therefore allows you to test your scripts against.

Since you're accessing restricted resources via the Nexus API, you always need to authenticate yourself. You can get your authorization token (to be provided as a "Authorization" bearer token), you need to access the authorization endpoint.

Contact

Any questions?

Find more information depending on:

Or contact us by e-mail: kg-team@humanbrainproject.eu