Search with DQL (GET) ​

GEThttps://kg.diffbot.com/kg/v3/dql

A GET flavor of DQL Search. If you prefer, the POST variant is also available.

Example ​

bash
curl --request GET \
  --url 'https://kg.diffbot.com/kg/v3/dql?token=<DIFFBOT_TOKEN>&query=type%3AOrganization%20locations.city.name%3A%22San%20Francisco%22%20nbEmployees%3E5000&size=2&filter=%24.name%3B%24.homepageUri%3B%24.nbEmployees' \
  --header 'Accept: application/json'
json
{
  "version": 3,
  "hits": 642,
  "results": 2,
  "kgversion": "477",
  "diffbot_type": "Organization",
  "facet": false,
  "textFallback": false,
  "data": [
    {
      "score": 1584.305,
      "entity": {
        "name": "Yandex",
        "homepageUri": "yandex.com",
        "nbEmployees": 26361
      },
      "entity_ctx": { "inner_hits": { "locations": [39] }, "matched_clauses": [] }
    },
    {
      "score": 1558.765,
      "entity": {
        "name": "Google",
        "homepageUri": "google.com",
        "nbEmployees": 187000
      },
      "entity_ctx": { "inner_hits": { "locations": [192, 161, 261, 215] }, "matched_clauses": [] }
    }
  ]
}

API Definition

Generated from v1.0.0 of the DQL API OpenAPI specification.

Search the Knowledge Graph using DQL

Request

Authentication
tokenquery
Cache and insert token into example requests (15d expiry)
Query parameters
typestring

Query type (default: query)

One of: querytextqueryTextFallbackcrawl

querystring required

DQL Query

colstring

Comma-delimited list of custom crawl collections to query. Specify all to query all collections for your token. This parameter is valid only when type=crawl and defaults to all (default: all)

frominteger (int32)

Return results starting at from index. from+size <= 10_000 for facet queries.

Please note that the from parameter is no longer applicable to Article queries and has been deprecated. In the future, using this parameter will result in an error.

(default: 0)

sizeinteger (int32)

Maximum number of results to return. -1 to return all results. from+size <= 10_000 for facet queries. (default: 50)

formatstring

Output format (default: json)

One of: jsonjsonlcsvxlsxlsx

exportspecstring

The spec defines the columns to export. This is applicable for csv, xls and xslx formats.

Export spec specifies how to export the entity JSON to a csv. A simple export spec looks like name;summary. To specify more complex export spec, including specifying how many of a list of industries to return, or the ideal employment record, see Exporting Columnar Format and JsonPath Filtering.

exportseparatorstring

The export separator

exportfilestring

For export endpoint, The file name of the export file

filterstring

Semi-colon separated path filter to filter response json. You can use a simple dot notation skills.name or a JsonPath expression such as $.name;$.locations.country.name. For more advanced options, see JsonPath Filtering for syntax.

filterExcludestring

Semi-colon separated path filter to filter and exclude data from response json. You can use a simple dot notation skills.name or a JsonPath expression such as $.name;$.locations.country.name. For more advanced options, see JsonPath Filtering for syntax.

jsonmodestring

extended returns origin information for facts. id returns just the diffbotIds and origins.

One of: extendedid

nonCanonicalFactsboolean

nonCanonicalFacts=true returns non-canonical facts. (default: false)

noDedupArticlesboolean

noDedupArticles=true indicates that articles should not be deduplicated but all of them returned (default: false)

clusterstring

Articles only. Utilize Diffbot clustering algorithms to identify related or similar objects.

  • cluster=all to return each article with a clusterId identifying thematically-similar articles.
  • cluster=best to remove thematically-similar articles from the result set, leaving a single best representative from each cluster.
  • cluster=dedupe to remove exact and near-duplicate articles from the result set. Where applicable, clusterId is returned in the entity_ctx element of each response entity.

One of: allbestdedupe

reportboolean

Generate coverage report. See Coverage Reports for more details on generating coverage reports for DQL queries. (default: false)

viewstring

Example request

bash
curl --request GET \
  --url 'https://kg.diffbot.com/kg/v3/dql?type=query&query=type%3AOrganization%20locations.city.name%3A%22San%20Francisco%22%20nbEmployees%3E5000&col=all&from=0&size=50&format=json&nonCanonicalFacts=false&noDedupArticles=false&report=false&token=<DIFFBOT_TOKEN>' \
  --header 'Accept: application/json'

Response

200Query results
versioninteger (int32)

Response version

hitsinteger (int64)
resultsinteger (int64)

Number of results in this response

kgversionstring

Version of KG that was queried

diffbot_typestring

Diffbot type of returned results

facetboolean

Was this a facet query?

dataobject[]

Results of the query

scorenumber (double)

score

entityobject

Entity. Can be null if no entity was found.

emptyboolean
entity_ctxobject

Entity-level context

errorsstring[]
callbackQuerystring

The query for the facet

upperBoundnumber (double)

The upper bound of the facet

lowerBoundnumber (double)

The lower bound of the facet

countinteger (int64)

The count of the facet

valuestring

The value of the facet

uristring

The uri of the facet value (for uri facets)

rewritesobject[]
querystring
reasonstring
textFallbackboolean

Whether the query fell back to text search.

reportIdstring

Identifier for the generated coverage report. Present only when report=true was passed.

json
{
  "version": 3,
  "hits": 642,
  "results": 2,
  "kgversion": "477",
  "diffbot_type": "Organization",
  "facet": false,
  "textFallback": false,
  "data": [
    {
      "score": 1584.3050537109375,
      "entity": {
        "name": "Yandex",
        "homepageUri": "yandex.com",
        "nbEmployees": 26361
      },
      "entity_ctx": {
        "inner_hits": {
          "locations": [
            39
          ]
        },
        "matched_clauses": []
      }
    },
    {
      "score": 1558.7650146484375,
      "entity": {
        "name": "Google",
        "homepageUri": "google.com",
        "nbEmployees": 187000
      },
      "entity_ctx": {
        "inner_hits": {
          "locations": [
            192,
            161,
            261,
            215
          ]
        },
        "matched_clauses": []
      }
    }
  ]
}
400Error parsing the query
errorboolean
messagestring
lineinteger
columninteger
htmlMessagestring

The message with the offending token wrapped in <mark> for display.

json
{
  "line": 1,
  "column": 6,
  "htmlMessage": "<span>type:<mark>:</mark>:Bogus((</span>",
  "error": true,
  "message": "Encountered \" \":\" \": \"\" at line 1, column 6."
}
401Unauthorized
codeinteger
messagestring
requestIdstring
json
{
  "code": 401,
  "message": "Unauthorized. Incorrect token.",
  "requestId": "a9cbf96bb0e2084d5c1595ae8f526576"
}
422Invalid or missing parameters
errorboolean
messagestring
json
{
  "error": true,
  "message": "Parameter 'query' not specified"
}
500Internal Server Error
codeinteger
messagestring
json
{
  "code": 500,
  "message": "HTTP 500 Internal Server Error"
}