Keys

All API requests must have a HTTP header with one of your API keys enabled for the intended operation (SPARQL access or API access).

You can manage your API keys from the dedicated panel, in your account: create as many keys as you want, and grant them the proper access for each.

SPARQL

To programmatically perform your queries on the SPARQL endpoint, send a GET request to https://query.semantic.builders/sparql adding the header api-key with a key enabled for "Access to SPARQL endpoint".

Here you find a few samples, in different languages:

API

Authentication

All requests must have a X-SB-Key header containing the value of one of your API key enabled for "Access to API".

Utilities

There are a few API endpoints in Semantic Builders exposed for your convenience.

The following endpoints can be used at no charge.

Available endpoints:

  • GET https://semantic.builders/api/probe

    To just test the authentication key given in the X-SB-Key header.

    If valid, returns a simple feedback payload.

    {
      "code": 200,
      "message": "OK"
    }

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.
  • GET https://semantic.builders/api/status

    To retrieve some information about the account, including the current credit and metrics about the usage within the current day.

    {
      "credit": 98.3722155098,
      "stats": {
        "storage": 645335,
        "queries": 43,
        "time": 421148
      }
    }

    Includes the attributes:

    • credit: still available credit, in Euro
    • storage: currently allocated storage, both for Saved Queries and Extractions, in kilobytes
    • queries: the number of queries executed today
    • time: the cumulative time spent executing queries, in milliseconds

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.

Retrieve Data

Semantic Builders exposed a simple API to access your Saved Queries and Extractions.

The following endpoints can be used at no charge.

Available endpoints:

  • GET https://semantic.builders/api/saved

    To access the list of your saved queries. This returns a JSON array, containing a JSON object for each query.

    [
      {
        "id": "4ab2b8bd-7ff6-4f6e-bb03-ae231f83fc21",
        "title": "My Saved Query",
        "access": "private",
        "created_at": "2024-09-08T13:49:00",
        "size": 5592572
      },
      {
        "id": "e749150d-f295-48d2-94fe-fec8d059fa3c",
        "title": "My Other Saved Query",
        "access": "private",
        "created_at": "2024-09-04T12:43:00",
        "size": 3070917
      }
    ]

    Each saved query is described by:

    • id - the unique identifier of the element; use it to retrive contents with the related API endpoint
    • title - the title assigned to the element
    • access - public or private, accordly to the settings
    • created_at - date of creation of the element
    • size - filesize, in bytes

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.
  • GET https://semantic.builders/api/saved/ID

    To access the actual contents of a given saved query, identified by the id (provided by the listing endpoint).

    Contents are returned in standard SPARQL Query Results JSON.

    {
      "head": {
        "vars": ["item", "itemLabel"]
      },
      "results": {
        "bindings": [
          {
            "item": {
              "type": "uri",
              "value": "http://www.wikidata.org/entity/Q378619"
            },
            "itemLabel": {
              "xml:lang": "en",
              "type": "literal",
              "value": "CC"
            }
          },
          {
            "item": {
              "type": "uri",
              "value": "http://www.wikidata.org/entity/Q498787"
            },
            "itemLabel": {
              "xml:lang": "en",
              "type": "literal",
              "value": "Muezza"
            }
          }
        ]
      }
    }

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.
    • 404 the required ID does not exists, or is not accessible with the given key.
  • GET https://semantic.builders/api/extracts

    To access the list of your extractions. This returns a JSON array, containing a JSON object for each query.

    [
      {
        "id": "d5b1bf94-c28b-4eb3-98df-9a8a703dc133",
        "title": "My Extraction",
        "created_at": "2024-09-08T13:49:00",
        "size": 8208027
      },
      {
        "id": "ae1b2ca2-eb0f-40e4-abe4-e1bfd323d97c",
        "title": "My Other Extraction",
        "created_at": "2024-09-04T12:43:00",
        "size": 8758045
      }
    ]

    Each extraction is described by:

    • id - the unique identifier of the element; use it to retrive contents with the related API endpoint
    • title - the title assigned to the element
    • created_at - date of creation of the element
    • size - filesize, in bytes

    Error codes:

    • 401 no key has been provided, or the provided one is invalid.
    • 403 the provided key is not enabled for API access.
  • GET https://semantic.builders/api/extracts/ID

    To access the actual contents of a given extraction, identified by the id (provided by the listing endpoint).

    Contents are returned in CSV.

    Q1868,"Paul Otlet",+1868-08-23T00:00:00Z,+1944-12-10T00:00:00Z
    Q23,"George Washington",+1732-02-22T00:00:00Z,+1799-12-14T00:00:00Z
    Q42,"Douglas Adams",+1952-03-11T00:00:00Z,+2001-05-11T00:00:00Z
    Q368,"Augusto Pinochet",+1915-11-25T00:00:00Z,+2006-12-10T00:00:00Z

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.
    • 404 the required ID does not exists, or is not accessible with the given key.

Entity Recognition

Semantic Builders provides an API to handle arbitrary texts and retrieve named entities from Wikidata, ready to be referenced within text's self metadata.

Each call to the following endpoints is individual charged accordly to the given pricing for the service.

Available endpoints:

  • GET https://semantic.builders/api/entities

    Parameters:

    • body the actual text you want to analyze. This can be a GET parameter, or just put in the HTTP request's body (suggested option for text longer than 2000 chars). If it is formatted in HTML, it is automatically flattered to plain text before execution. An empty result set is returned if the length of "body" is <= 10 characters.
    • language [optional] the language of the text. May have one of the following values:
      • en English
      • fr French
      • de German
      • it Italian
      • ja Japanese
      • pt Portuguese
      • ru Russian
      • es Spanish
      If not specified, or if not recognized, the language is auto detected.

    To analyze a text and retrieve references to Wikidata entities. This returns a JSON array, containing a JSON item for each identifier named entity.

    [
      {
        "entity": "Japan",
        "wikidata": "https://www.wikidata.org/wiki/Q17"
      },
      {
        "entity": "Tokyo",
        "wikidata": "https://www.wikidata.org/wiki/Q1490"
      },
      {
        "entity": "Sapporo Snow Festival",
        "wikidata": "https://www.wikidata.org/wiki/Q929531"
      }
    ]

    Each item in response is described by:

    • entity - the recognized named entity
    • wikidata - the link to the same Wikidata entity

    Error codes:

    • 400 no key has been provided.
    • 401 the provided key is invalid.
    • 403 the provided key is not enabled for API access.
    • 403 the provided key is not enabled for API access