API beta
Get programmatic access to the data and start building on the entire data. This service is accessible to everyone.
API authentication
A personal token is needed to use the API, sign up to get yours:
Getting started
- The API base url is
https://api.workwithdata.com/v1/ - An authorization header is required in the following format:
"Authorization: Bearer <your_token>"
Endpoints
extract/<table>
Available tables: companies (more tables to be added soon)
Query parameters (optional):
| Parameter name | Type | Definition | Possible values |
|---|---|---|---|
| limit | Optional | Maximum number of rows to be returned | Integer >= 1 |
| f | Optional | Number of filters to apply to the companies table | Integer >= 1 |
| fcol[x] | Required if f exists | Name of the filtering column x | See available data below |
| fval[x] | Required if f exists | Value of the filter on the column X | |
| fop[x] | Required if f exists | Operator used to filter the column x | Depending on the type of fcol[X]
For texts: = (exact match) != (exact exclusion) Includes (approximate match) Excludes (approximate exclusion) For numbers: >= <= > < = != |
To create the right query paramaters, we recommend you to first create the data you want to extract on the dataset page and then use the structure of the dataset page for the API.
Fields available for the filtering in query paramaters:
- company (text): name of the company
- sector (text) : values from the GICS
- industry (text) : values from the GICS
- website (text): the full URL of the company’s website
- domain (text): the URL of the company’s website without protocol and prefix
- foundation_year (number): year where the company was founded
- city (text): city of the headquarter
- country (text): country of the headquarter
- employees (number): number of employees
- employee_type (text): if the number of employees is estimated by us or not (possible values: estimate/actual)
- revenues (number): in $
- revenue_type (text): if the revenue is estimated by us or not (estimate/actual)
- talking_points (text): concatenation of different descriptions of the companies, coming from different sources such as the website or social media
- stack (text)
- linkedin_link (text): link to the LinkedIn profile of the company
- linkedin_followers (number): number of followers on LinkedIn
- twitter_link (text): link to the Twitter profile of the company
- twitter_followers (number): number of followers on Twitter
- facebook_link (text): link to the Facebook profile of the company
- instagram_link (text): link to the Instagram profile of the company
Response
Your JSON API results are in the following format:
| Parameter name | Definition |
|---|---|
| currency | String(3) - the currency of your subscription |
| is_paid | Boolean - True if the data is paid, False if it is free |
| price | Float - Amount that is added to your next invoice in the currency of your subscription |
| results | List of dicts- results of the query. Each row is an element of the list |
| results_length | Integer - Size of the results of your query |
| returned_length | Integer - Size of the results returned by the API. Usually equals to results_length, except if you reach your monthly API usage limit with a query. When that is the case, we truncate the results so that you don't exceed your limit. |
Example:
{
"currency": "USD",
"is_paid": true,
"price": 0.005,
"results":
[{
"city":null,
"company":"Tessian",
"country":"United States",
"domain":"tessian.com",
"employee_type":"estimate",
"employees":225,
"facebook_link":null,
"foundation_year":2013,
"industry":"Software",
"instagram_link":"https://www.instagram.com/tessianofficial",
"linkedin_followers":16611,
"linkedin_link":"https://www.linkedin.com/company/tessian",
"revenue_type":"estimate",
"revenues":42275000.0,
"sector":"Information Technology",
"stack":"google analytics",
"talking_points":"Intelligent Cloud Email Security For The Modern Enterprise ...",
"twitter_followers":2620,
"twitter_link":"https://twitter.com/tessian",
"website":"https://www.tessian.com"
}],
"results_length": 1,
"returned_length": 1
}Examples
Here are a few examples from which you can create your own:
- Exact search for a specific company:
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=1&fcol0=website&fop0==&fval0=https://www.tessian.com" - Approximate search for a company:
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=1&fcol0=domain&fval0=tessian&fop0=includes" - Search for companies in France, Paris (2 filters applied):
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=2&fcol0=city&fop0==&fval0=paris&fcol1=country&fop1==&fval1=france"
