On Sunday, May 4th, we released v2.0 of the CrunchBase API into beta.
The response from our developer community has been fantastic; developers and partners have registered over 700 applications in the past 10 days and feedback has been pouring into api@crunchbase.com.
The goal of our beta is to gather as much input from the community as possible before we finalize the core of the API. We know that once we establish the API’s fundamental structure, changes have huge disruptive implications. It’s critical to us that we build the right foundation for what will ultimately become a very rich and powerful tool.
Here’s a summary of what we’ve heard to-date:
Search
Probably the top-requested feature for the API is one we knew we’d omitted when we started the beta. Rather than assume we knew how people would want to search the data, we wanted to hear from the community. Here’s what we’ve heard:
- Search all (Organizations, People, and Products) by name
- Search / Filter Organizations
- by Name
- by Domain Name
- by Country, Region, City
- by Category / Categories
- by Type (e.g., Company, Investor, etc.)
- by Funding (type, date, amount)
- by Acquisition (date, amount)
- Search / Filter People
- by Name
- by Country, Region, City
- by Type (investor)
Supporting these search parameters will mean that we’ll also need to release two new collection endpoints, as follows:
https://api.crunchbase.com/v/2/categories
https://api.crunchbase.com/v/2/locations
The latter (locations) may initially be released without query parameters. Ultimately, however, we will enable developers to both search the endpoint by name restrict the results to a Country or Region.
Missing Fields
The second most common piece of feedback is that the new API is missing some information that was available in the v1.0 API. Whereas some of this information has moved into relationships, some fields were omitted. Specifically, we’ll be adding the following:
- Organization
- Stock Exchange / Stock Symbol
- Public / Private
- Number of Employees
- Total Funding
- Phone Number
- Website / Homepage
- Investors (relationships)
- Past Team Members (relationships)
- Board Members & Advisors (relationships)
- Person
- Under experience and primary_affiliation, Organization should have a path
- Under experience and primary_affiliation, the items should have an is_current / is_past attribute
- Each degree item should have the Organization / School name and path
- Degree
- Each degree item should have the Organization / School name and path
- Address / Office
- When available, the item should include lat / long
created_at and updated_at
Although we released the beta API with support for ordering the results by “updated_at DESC”, we failed to include the updated_at timestamp. This means that developers can’t actually retrieve “everything that changed since I last checked.” We’ll be making the following changes:
- Add created_at / updated_at collection endpoints
- /organizations
- /people
- /products
- Add created_at and updated_at to detail endpoints
- property of organization. people, or product
- property of every related item
- Add created_at and updated_at to newly-created search endpoint
Ultimately, we want to support filtering any collection endpoint by updated_at so a developer could make a request that looked something like the following:
https://api.crunchbase.com/v/2/organizations?updated_since=1400193464
We’re still debating whether it’s efficient or appropriate to support this level of granularity.
Errors & Error Handling
A number of users have reported intermittent 500 errors, and we’re looking into the source of those issues.
In addition, users have appropriately reported that we should return errors in JSON as opposed to HTML. We’ll switch from returning a 404 / HTML (and other errors) to returning errors in well-formed JSON.
Naming Inconsistencies
In some cases, we are inconsistent between the name of a relationship in the API and the name of a card or property on the front-end. An example of this is Categories. In the API, we refer to these “markets”, whereas on CrunchBase we call them Categories, as seen here:
markets: { paging: { total_items: 7, first_page_url: "https://api.crunchbase.com/v/2/organization/facebook/markets", sort_order: "created_at DESC" }, items: [ {type: "Market",name: "Networking"}, {type: "Market",name: "Communities"}, {type: "Market",name: "Colleges"}, {type: "Market",name: "Identity"}, {type: "Market",name: "All Students"}, {type: "Market",name: "Facebook Applications"}, {type: "Market",name: "Social Media"} ] }
versus
We will make the naming consistent between the front-end and the API across all data elements and relationships.
More Feedback?
We’re almost done with our beta period (it ends on Saturday). If you have any feedback to share, please reach out to use at api@crunchbase.com and let us know. The excitement around the new API has been fantastic and we look forward to launching the final version and start working on the features that will give our developers access to the rich data inside CrunchBase!
