Constructing People Queries

The Datafiniti API lets you build out a wide variety of search queries so you can get the exact data you want.

Querying a single field

The simplest query you can do is querying a single field. Here's an example:

{
	"query": "city:Austin"
}

This tells the API to search the people database for any person that works in Austin.

You can do similar queries on any of the fields in the people schema. Here's an example that queries the businessName field:

{
	"query": "businessName:Apple"
}

Querying multiple fields

You can run more complicated queries by combining fields with various boolean operators (e.g., AND OR). For example:

{
	"query": "businessName:Apple AND city:Austin"
}

This returns any people who work at Apple in Austin.

You can use the OR operator to run broader queries. For example:

{
	"query": "businessName:Apple OR businessName:Dell"
}

That's not all though. We can group fields and operators with parentheses to do some really fancy stuff:

{
	"query": "(businessName:Apple OR businessName:Dell) AND city:Austin"
}

Querying multiple values

If you want to query multiple values within the same field, there is a simple way to do this. For example:

{
	"query": "businessName:(Apple OR Dell OR Microsoft)"
}

This returns any people who work at Apple, Dell, or Microsoft. This is much simpler than:

{
	"query": "businessName:Apple OR businessName:Dell OR businessName:Microsoft"
}

Wildcards

You can use * to query a field for any value, like this:

{
	"query": "emails:*"
}

This will return any people that have an associated email address. This is helpful if we want to make sure any people we get back are guaranteed to have certain fields filed out.

Wildcards can do more though. You can also append * to the value we're searching on to broaden its potential matches. For example:

{
	"query": "jobTitle:invest*"
}

This will return people with any of the following in their jobTitle field: invest, investor, investment, investing, and so on.

Range queries

Any fields that are dates, integers, or doubles will let you search them based on a range.

{
	"query": "dateAdded:[2018-01-01 TO 2018-02-01]"
}

will return all people that have been added to the database between Jan 1, 2018 and Feb 2, 2018.

You can do unbounded range queries as well, like:

{
	"query": "dateAdded:[2018-01-01 TO *]"
}

This will return all people have been added since Jan 1, 2018 until the current date.

You can also use comparison operators like >, >=, <=, and <. These are helpful when you want to search for products that are cheaper or more expensive than certain limits. E.g.:

{
	"query": "numEmployeesMin:>10"
}

returns all people who work at companies with more than 10 employees.

Excluding values

For some searches, you'll want to exclude certain values from returning. For example, let's say you wanted to find all engineers, except for software engineers. You would use the - operator to negate software values:

{
	"query": "jobTitle:engineer AND -jobTitle:software"
}

Count Feature

As an alternative or used for testing purposes you can set your num_records to 0 in your people search query. This is will only return the num_found of the query and will cost 0 credits to search. Try it out

{
  "query": "country:US",
  "num_records":0
}

📘

Count Feature

Please note that this is feature is only for paid accounts. So please check your account plan or contact [email protected].

Paging Over Results

As an alternative to running a download, you can also use the API to page through the data. This approach allows you to consume one chunk at a time.

POST https://api.datafiniti.co/v4/products/paginate?page=1&limit=50
{
  "query": "keys:*"
}

The pagination endpoint uses the following parameters:

• page - You specify which chunk of data you would like to access. You can iterate the page to work your way through all of the results. You cannot paginate further than the 10,000th record.
• limit - This specifies the number of results you want returned within the page. The maximum number of results that can be returned per page is 1,000.