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".

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": "dd922d30-5e77-4b89-b224-5346539779e5",
        "title": "My Saved Query",
        "access": "private",
        "created_at": "2023-08-29T10:56:30",
        "size": 4374295
      },
      {
        "id": "e2a40ffd-7ec7-4b72-86fd-f3a3adbf5e3e",
        "title": "My Other Saved Query",
        "access": "private",
        "created_at": "2023-08-25T09:50:30",
        "size": 5937917
      }
    ]

    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:

    • 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/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:

    • 401 no key has been provided, or the provided one 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": "4e0cb1f5-c660-4481-ad54-67f74d73da14",
        "title": "My Extraction",
        "created_at": "2023-08-29T10:56:30",
        "size": 2549100
      },
      {
        "id": "644454e1-72f4-45bd-b48c-2718e96137e1",
        "title": "My Other Extraction",
        "created_at": "2023-08-25T09:50:30",
        "size": 584403
      }
    ]

    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:

    • 401 no key has been provided, or the provided one 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. 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, 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:

    • 401 no key has been provided, or the provided one is invalid
    • 402 your account has not enough credit to perform the task
    • 403 the provided key is not enabled for API access