To make podcasts accessible to as many people as possible, we built two things at Listen Notes:
- An easy-to-use podcast search engine website for most people in the world: ListenNotes.com
- An easy-to-use & no-nonsense podcast API for developers (we call it “Listen API”): ListenNotes.com/api/
We just launched a new(-ish) version of Listen API. We call it “Listen API v2”: https://www.listennotes.com/api/
A brief history of Listen API
We launched Listen API v1 in early December 2017, almost 1.5 years ago. To quickly launch the API, we used a 3rd party API gateway called Mashape, which helped us handle billing and do analytics. Mashape was acquired by a venture-backed startup RapidAPI, and they merged Mashape into RapidAPI.com. RapidAPI is a marketplace for APIs. Listen Notes is an API provider on RapidAPI. Developers subscribe to Listen API via RapidAPI, and RapidAPI takes 20% of our revenue.
Generally, I’m satisfied with Mashape & RapidAPI, because I can defer the engineering work of building the billing & analytics stuffs for our API offering and focus on other then high-priority tasks.
In short, Listen API v1 runs on a 3rd party platform RapidAPI.
Why Listen API v2?
There are more and more apps & services using Listen API. This may not be obvious to many people. But this is actually happening.
As we serve more and more developers, we require the API gateway to be fast, stable, and highly customizable. We have to get100% control on the critical piece of infrastructure: the API gateway. Therefore, we have to replace RapidAPI with our own in-house software.
Thus, we launched Listen API v2, so we can have 100% control.
What’s the difference between v1 and v2?
Listen API v1 and v2 both provide exactly the same endpoints with the same parameters & the same JSON responses.
The major difference is in the FREE plan and the billing.
In v1, as we use RapidAPI to host our Listen API, they require you to enter credit card info even when you just want to use the FREE plan. In v2, you can just use the FREE plan without entering your credit card info.
In v1, you’ll get charged when you quota limit of FREE plan — this is not actually free. In v2, you’ll be suspended in this case. To be specific, when you exceed quota limit in FREE plan of v2, you’ll get HTTP 429 in the response. We reset stats in the next billing cycle.
In v1, you need to subscribe to one of many paid plans, each of which has different quota limits. And in the same paid plan, different types of endpoints have different quota limits. This is complex and confusing. In v2, we provide only one paid plan: PRO. The PRO plan has a base price $20/month, which include 100k requests. All endpoints in v2 are treated as the same. When you exceed 100k requests quota limit, you’ll be charged per extra 1000 requests. Similar to other popular APIs (e.g., Google Maps API), we have tiered pricing. The more you use, the more discount you’ll get.
The following two images show the pricing models of Listen API v1 and v2.
Pricing of Listen API v1
Pricing of Listen API v2
How to migrate from v1?
If you are already using v1, you just need to do two small things to migrate to v2:
- Subscribe to either FREE or PRO plan on this page.
- In your code, change the base url to https://listen-api.listennotes.com, change the version number to v2 in all endpoints, and use the new API key in the X-ListenAPI-Key header. You can simply copy the entire endpoint url from the docs page.
Migrate from v1 to v2
Listen API v1’s response headers X-RateLimit-* don't exist in v2. Instead, you can find response headers X-ListenAPI-FreeQuota and X-ListenAPI-Usage when using Listen API v2.
Will you sunset Listen API v1?
No.
We will keep Listen API v1 up and running. Please take your time to migrate to v2. But all the future improvements will only go to Listen API v2.
We’ll use tons of API requests. Are you able to support our scale?
Yes.
Right now, there are developers doing millions of requests/month with Listen API. We can easily support at least 10x of current traffic without adding more servers.
And please do try out the price calculator in v2:
Price calculator for Listen API’s PRO plan.
Last but not least, you can always contact me at:
hello@listennotes.com
I reply emails very fast, if it’s about Listen API :) You talk to me directly, who built this whole thing by hand and by heart.
