Input Parameters - Company Search API

Detailed information on the input parameters used for the Company Search API

Note: While all input parameters are optional, you must provide either a query or an sql parameter (but not both.)

Optional Parameters

query

Parameter Name

Required

Description

Default

Example

query

No

An Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.

{"query": {"term": {"name": "people data labs"}}}

Building a Query

You must provide a value for either the query or the sql parameter to receive a successful response. The query value should align directly with the Elasticsearch DSL. SQL queries are executed using Elasticsearch SQL. Most typical query types are available but some are excluded. For all available query types see here.

When an API request is executed, the query is run directly against our Company dataset without doing any additional cleaning or pre-processing. This means that you have a ton of freedom to explore the dataset and return the perfect records. It also means that understanding the available fields can be very helpful to making successful queries.

You can find field descriptions here and the Elasticsearch mapping underlying this API here.

Query Limitations

The following Elasticsearch query types will be accepted:

Most specialized options are disabled, such as boosting and custom scoring. No aggregations are allowed.

Any SQL query that translates to the above query types through the ES SQL translate API will be accepted. This means most basic SQL, NO JOIN and GROUP BY commands, and so forth.

Any array found in the query (such as a terms array) will have a hard limit of 100 elements. Any query containing an array surpassing this limit will be rejected.

sql

Parameter Name

Required

Description

Default

Example

sql

No

A SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving PDL fields. Any use of column selections or the LIMIT keyword will be ignored.

SELECT * FROM company WHERE name='people data labs'

size

Parameter Name

Required

Description

Default

Example

size

No

The batch size or the maximum number of matched records to return for this query if they exist. Must be between 1 and 100.

1

100

from

Parameter Name

Required

Description

Default

Example

from

No

[LEGACY] An offset value for paginating between batches. Can be a number between 0 and 9999. Pagination can be executed up to a maximum of 10,000 records per query.

Note: FROM CAN NOT BE USED WITH SCROLL_TOKEN IN THE SAME REQUEST.

0

0, 100, 200 ...

scroll_token

Parameter Name

Required

Description

Default

Example

scroll_token

No

An offset key for paginating between batches. Unlike the legacy from parameter, you can use this for any number of records. Each Company Search API response returns a scroll_token that you can use to fetch the next size records.

None

104$14.278746

titlecase

Parameter Name

Required

Description

Default

Example

titlecase

No

All text in API responses is returned as lowercase by default. Setting titlecase to true will titlecase any records returned.

false

true

pretty

Parameter Name

Required

Description

Default

Example

pretty

No

Whether the output should have human-readable indentation.

false

true

api_key

Parameter Name

Required

Description

Default

Example

api_key

No

Your API key.

Note: you can also provide this in the request header instead, as shown on the Authentication page.



Did this page help you?