Query Types

There are two types of queries: type and id.

Type Queries

A type query allows you to use various query operators to describe a search criteria. A simple type query looks like this:

type:Organization locations.city.name:"San Francisco" nbEmployees>5000

This query searches for all Organizations (type:Organization) located in San Francisco (locations.city.name:"San Francisco") with more than 5000 employees (nbEmployees>5000).

This query is simple but demonstrates the structure of a type query - a type clause followed by one or more filter clauses. Filter clauses constrain values of fields like locations.city.name and nbEmployees. Filters are optional, but in most cases you would want to use filters to get meaningful results.

Note that fields use a dot-notation to refer to specific elements in the JSON responses. locations.city.name would then refer to a field like this:

{
   ...,
   "locations": {
      ...,
      "city": {
         "name": "San Francisco"
      }
   }
}

You can view the results in JSON format by calling the API directly. Note that some of these responses can be very large.

🚧

You will be charged credits for executing the query below.

You can control the number of credits by changing the size parameter. Start with size=5 to get an idea of the output. Substitute YOURDIFFBOTTOKEN with your Diffbot token in the script below.

TOKEN=YOURDIFFBOTTOKEN
curl --request GET \
     --url "https://kg.diffbot.com/kg/v3/dql?token=${TOKEN}&size=5&query=type%3AOrganization+locations.city.name%3A%22San+Francisco%22+nbEmployeesMin%3E5000" \
     --header 'Accept: application/json'

https://kg.diffbot.com/kg/v3/dql?token=${TOKEN}&size=5&query=type%3AOrganization+locations.city.name%3A%22San+Francisco%22+nbEmployeesMin%3E5000

ID Queries

You can query the Knowledge Graph directly if you know the unique identifier (ID) of the entity you are interested in accessing. The query format is id:id-string.

For example, you can query for the Facebook entity id:Ebm4UJoSuP1esww1rsLvu9g in the dashboard.