Getting Started

This page will help you get started with the Evenings API.

Welcome to the Evenings API! Whether you’re building an application or integrating with our streaming service, this guide will help you get started smoothly. In just a few steps, you'll be ready to interact with the Evenings API to enhance your application with our stations' information.

Step 1: Understanding the Evenings API

The Evenings API provides endpoints to retrieve information about stations, tracks, and stream status. Familiarize yourself with the three main endpoints:

1. GET /v1/streams/{stream}/public: Get public stream information.

2. GET /v1/stations/{station}/tracks: Get a list of tracks for a station.

3. GET /v1/stations/{station}/status: Get the status of a station.

Note: The GET /v1/stations/{station}/broadcasts endpoint is deprecated and has been replaced by GET /v1/stations/{station}/tracks.

Step 2: Authentication

Before making requests, you need an API key to authenticate. Follow these steps to authenticate your requests:

1. Obtain an API key by contacting [e-mail] or via direct message at @EVENINGSFM on Twitter.

2. Use the Bearer token method for authentication.

3. Include the API key in the Authorization header like so: Authorization: Bearer YOUR_API_KEY.

Replace YOUR_API_KEY with the key you received.

Step 3: Making Your First Request

To start interacting with the Evenings API, make a simple GET request to any of the public endpoints. Here’s how you can make a request to retrieve public stream information:

HTTP

GET https://api.evenings.co/v1/streams/eveningsfm/public

Replace eveningsfm with the slug of the station you are interested in.

Step 4: Handling Responses

The Evenings API will return responses in JSON format. Ensure your application can parse JSON and handle the data accordingly.

For instance, when fetching station tracks, your application should be prepared to handle an array of track objects, each with details such as title, location, and duration.

Step 5: Error Handling

Understand and handle errors correctly:

• If you receive a 4xx status code, it often indicates an issue with your request (like a bad request or unauthorized access).

• A 5xx status code indicates a problem on the Evenings API server.

Refer to the HTTP status codes for proper error handling.

Step 6: Best Practices

• Avoid making unnecessary requests; cache responses where possible.

• Respect the rate limits to prevent being blocked.

• Secure your API key; do not expose it in client-side code.

Step 7: Getting Support

If you encounter any issues or have questions:

• Contact [e-mail] for support via email.

• Send a DM to @EVENINGSFM on Twitter.

By following these steps, you should be well on your way to successfully integrating with the Evenings API. Happy coding!