Input Parameters - Company Search API
Required Parameters
You must provide either the query
or the sql
parameter (but not both) to receive a successful response. We recommend using the Elasticsearch query
parameter for most use cases.
When you execute an API request, the query runs directly against our Company Dataset without any cleaning or preprocessing. This means that you have a lot of freedom to explore the dataset and return the perfect records for your particular use case. It also means that you will need to understand the available fields to make successful queries.
Use the field descriptions on the Company Schema and the underlying Elasticsearch Mapping to help write better queries.
To help you identify how to best query for specific sub-entities (schools, companies, and locations), we offer a suite of Cleaner APIs.
We also provide a free Query Builder Tool to help write and test Elasticsearch queries for our Search APIs.
api_key
api_key
Type | Description | Default | Example |
---|---|---|---|
String | Your secret API key. |
Your API Key must be included in either the request header or the api_key
parameter. For more information about request authentication, see the Authentication page.
Optional Parameters
query
query
Type | Description | Example |
---|---|---|
Object | An Elasticsearch (v7.7) query involving our company fields. See our underlying Elasticsearch mapping for reference. | {"query": {"term": {"name": "people data labs"}}} |
Elasticsearch Query Limitations
We accept the following Elasticsearch query types:
We've disabled most specialized options, such as boosting and custom scoring, and we do not allow aggregations.
Any array in a query (such as a terms
array) will have a hard limit of 100 elements. If a request goes over this limit, it will fail.
sql
sql
Type | Description | Example |
---|---|---|
String | An SQL query of the format: SELECT * FROM company WHERE XXX , where XXX is a standard SQL boolean query involving our company fields. | SELECT * FROM company WHERE name='people data labs' |
SQL Query Limitations
We execute SQL queries using Elasticsearch SQL.
We accept any SQL query that translates to the above Elasticsearch query types through the ES SQL translate API.
We will ignore any use of column selections or the LIMIT
keyword.
We limit the number of wildcard terms (using LIKE
with %
) to 20 per request. If a request goes over this limit, it will fail.
size
size
Type | Description | Default | Example |
---|---|---|---|
Integer | The maximum number of matched records to return for this query if they exist. Must be between 1 and 100 . | 1 | 100 |
from
from
Legacy Field
The
from
parameter is deprecated. Usescroll_token
instead.
Type | Description | Default | Example |
---|---|---|---|
Integer | [LEGACY] An offset value for paginating between batches, which must between 0 and 9999 . We will execute pagination for a maximum of 10,000 records per query.Note: You cannot use from and scroll_token in the same request. | 0 | 100 |
scroll_token
scroll_token
Type | Description | Default | Example |
---|---|---|---|
String | Each search API response returns a scroll_token . Include it in the next request to fetch the next size matching records.Unlike the legacy from parameter, you can use this parameter for any number of records.Note: You cannot use from and scroll_token in the same request. | 104$14.278746 |
A scroll_token
returns in every Company Search API response and serves as a placeholder or bookmark for the last record received. For queries with more results than can fit in a single API response (see the size
field), use the scroll_token
to get the next batch of results.
For example, if you send a query to the Company Search API that has 10,000 matches, you will need multiple API calls to retrieve all the records. The scroll_token
represents how far along you are in that list of records.
Generally, the way to use scroll_token
is:
- Send a query to the Company Search API.
- Get a response back containing one batch of records as well as a
scroll_token
response value (if you have already retrieved all the available records in this batch, then thescroll_token
value will benull
). - Use the same query from Step 1 and the
scroll_token
you just received to make another request to the Company Search API. - Get another response back with the next batch of records and a new
scroll_token
value. - Repeat steps 3 and 4 until you have received the desired number of records or until you receive a 404 status code because pagination is complete and the
scroll_token
key is missing from the response.
For a detailed working example of this process, see the following code example: Bulk Retrieval.
titlecase
titlecase
Type | Description | Default | Example |
---|---|---|---|
Boolean | All text in API responses returns as lowercase by default. Setting titlecase to true will titlecase any records returned instead. | false | true |
pretty
pretty
Type | Description | Default | Example |
---|---|---|---|
Boolean | Whether the output should have human-readable indentation. | false | true |
updated_title_roles
updated_title_roles
Type | Description | Default | Example |
---|---|---|---|
Boolean | Temporary parameter. Set to true to return the updated taxonomy for job_title_role and job_title_subrole along with the new job_title_class field. | false | true |
Updated 6 days ago