Using Search API
Instructions on how to use Crunchbase's Search API endpoints
The Search API endpoints are provided so you can...
- Retrieving data for a group of entities / an entire collection
- Finding entities that match certain criteria
We provide the Search API endpoints for many of our collections - e.g. organizations, people, funding rounds, and acquisitions. If any ranges or limitations exist, they will be noted within the reference documentation. For details on all of our collections, please visit our Legacy API Reference page
To make a request using our Search APIs, you must provide the following (in no particular order):
- a user key
- a request body that contains "field_ids" and "query"
- important note: each search filter within "query" are AND'ed together; if you would like to use OR, please use multiple search calls
You can also further customize the API response for your search by...
- including "order" in the body request to sort the result based on a particular field
- including "limit" in the body request to limit how many results are returned per page
Search "Query" Supports "AND" Only
Each search filter within "query" are AND'ed together. This means if you have "categories" = "SaaS" and "location" = "San Francisco" for a company search, the response will return companies that are BOTH in San Francisco AND belong to the SaaS category.
If you would like to use OR, please use multiple search calls. For the above example, you would execute two company search calls - one company search call to find companies that are in San Francisco, then another company search call to find companies that belong to the SaaS category.
API Support Only JSON
We currently support only JSON (as input and output) for our API endpoints; as such, when you are sending a request and need to specify the type of content, please also default to JSON. (this is mostly relevant for POST requests' payload)
POST https://api.crunchbase.com/api/v4/searches/funding_rounds?user_key=INSERT_KEY_HERE
--Body Request--
{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"order": [
{
"field_id": "announced_on",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "announced_on",
"operator_id": "gte",
"values": ["2012"]
},
{
"type": "predicate",
"field_id": "num_investors",
"operator_id": "lte",
"values": ["4"]
},
{
"type": "predicate",
"field_id": "money_raised",
"operator_id": "gte",
"values": [
{"value": 10000000, "currency": "usd"}
]
}
],
"limit": 100
}
curl --request POST 'https://api.crunchbase.com/api/v4/searches/funding_rounds?user_key=INSERT_KEY_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"order": [
{
"field_id": "announced_on",
"sort": "asc"
}
],
"query": [
{
"type": "predicate",
"field_id": "announced_on",
"operator_id": "gte",
"values": ["2012"]
},
{
"type": "predicate",
"field_id": "num_investors",
"operator_id": "lte",
"values": ["4"]
},
{
"type": "predicate",
"field_id": "money_raised",
"operator_id": "gte",
"values": [
{"value": 10000000, "currency": "usd"}
]
}
],
"limit": 100
}
50 items are returned by default; 1000 items max
When using the Search API endpoints, if "limit" is not specified in your body request, the Search API will return a max of 50 items per page.
If you want to get the maximum number of results, you can request for as many as 1000 items per page with the "limit" parameter. If you request for more than 1000 items, you will get a MD403 error stating that "search limit cannot exceed 1000".
Pro Tips: find permalink & UUID easily
Want to find the permalink or UUID for an entity or category/location as input to your search?
- Go to www.crunchbase.com to find the entity you want, then take the last portion of the URL to get your permalink --> https://www.crunchbase.com/organization/{permalink}
- Use the autocomplete API - more details here
How do I know what data are available to be returned in the response?
You can quickly see what data fields are available to be returned in the response for each collection by going to the specific endpoint's response schema.
- The field names listed under "Entities" are what you will put as the value for "field_ids"
Steps by Steps:
-
- First go to the endpoint that you are interested in (let's say Search for Organization)
-
- Scroll down to the Responses section
-
- Click on Schema (screenshot below)
Expect all data fields to be optional
Unless otherwise called out as a required field in the response schema, please configure your system/process to treat data fields in the response as optional fields.
how do I paginate to the next page?
API 4.0 now uses keyset pagination to retrieve the next set of results. It will enable you to traverse our dataset faster, and it will also mitigate the performance deprivation that would occur paginating deep into a collection using API 3.1. Additionally, keyset pagination also helps ensure that you will never miss an entity since the keys remain constant even when the set changes.
To paginate to the next page:
- Include "after_id" in your body response and the uuid of the last item in your current page
- ex: "after_id": "5972288b-8188-475a-b153-1b6eb4d57fb1"
To paginate to the previous page:
- Include "before_id" in your body response and the uuid of the first item in your current page
Below is an example:
--Body Request: Next Page--
{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"query": [
{
"type": "predicate",
"field_id": "money_raised",
"operator_id": "gte",
"values": [
{"value": 10000000, "currency": "usd"}
]
}
],
"limit": 100,
"after_id": "52e7351a-7744-4ca6-b0df-d39a31740fbc"
}
--Body Request: Previous Page--
{
"field_ids": [
"identifier",
"announced_on",
"funded_organization_identifier",
"money_raised",
"investment_type"
],
"query": [
{
"type": "predicate",
"field_id": "money_raised",
"operator_id": "gte",
"values": [
{"value": 10000000, "currency": "usd"}
]
}
],
"limit": 100,
"before_id": "6bc24ac4-e062-458b-b70c-b4cb5918439c"
}
Processing Entire Collections
An alternative to paginating through an entire collection via the Search API is to use the Complete Node List export. This alleviates the need to paginate and may work better if you prefer to work with CSV files.
Updated about 2 months ago