Skip to content

Commit d94e86d

Browse files
committed
Update README.md.
1 parent ce7e7b6 commit d94e86d

File tree

1 file changed

+61
-0
lines changed

1 file changed

+61
-0
lines changed

README.md

+61
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ If you have any questions, please contact [[email protected]](hello@listenno
1414

1515
**Table of Contents**
1616
- [Podcast API Python Library](#podcast-api-python-library)
17+
- [Installation](#installation)
18+
- [Requirements](#requirements)
19+
- [Usage](#usage)
20+
- [Handling exceptions](#handling-exceptions)
1721
- [API Reference](#api-reference)
1822
- [Full-text search](#full-text-search)
1923
- [Typeahead search](#typeahead-search)
@@ -40,6 +44,63 @@ If you have any questions, please contact [[email protected]](hello@listenno
4044
- [Fetch audience demographics for a podcast](#fetch-audience-demographics-for-a-podcast)
4145

4246

47+
## Installation
48+
49+
Install [the official PIP package](https://pypi.org/project/podcast-api/) of the Listen Notes Podcast API:
50+
51+
```sh
52+
pip install --upgrade podcast-api
53+
```
54+
55+
You can also install from source:
56+
57+
```sh
58+
make && source venv/bin/activate
59+
```
60+
61+
### Requirements
62+
63+
- Python 3.5+
64+
65+
## Usage
66+
67+
The library needs to be configured with your account's API key which is
68+
available in your [Listen API Dashboard](https://www.listennotes.com/podcast-api/dashboard/#apps). Set `api_key` to its
69+
value:
70+
71+
```python
72+
from listennotes import podcast_api
73+
74+
api_key = 'a6a1f7ae6a4a4cf7a208e5ba********'
75+
76+
client = podcast_api.Client(api_key=api_key)
77+
78+
response = client.search(q='star wars')
79+
80+
print(response.json())
81+
```
82+
83+
If `api_key` is None, then we'll connect to a [mock server](https://www.listennotes.com/podcast-api/tutorials/#faq0) that returns fake data for testing purposes.
84+
85+
86+
### Handling exceptions
87+
88+
Unsuccessful requests raise exceptions. The class of the exception will reflect
89+
the sort of error that occurred.
90+
91+
| Exception Class | Description |
92+
| ------------- | ------------- |
93+
| AuthenticationError | wrong api key or your account is suspended |
94+
| APIConnectionError | fail to connect to API servers |
95+
| InvalidRequestError | something wrong on your end (client side errors), e.g., missing required parameters |
96+
| RateLimitError | for FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit |
97+
| NotFoundError | endpoint not exist, or podcast / episode not exist |
98+
| PodcastApiError | something wrong on our end (unexpected server errors) |
99+
100+
All exception classes can be found in [this file](https://github.com/ListenNotes/podcast-api-python/blob/main/listennotes/errors.py).
101+
102+
And you can see some sample code [here](https://github.com/ListenNotes/podcast-api-python/blob/main/examples/sample.py#L17).
103+
43104

44105

45106
## API Reference

0 commit comments

Comments
 (0)