Skip to content

REST Radio APIs (Version 4)

Cameron Fleming edited this page Aug 1, 2018 · 3 revisions

tmw.media Radio API

Correct for version: 4.0 (latest)

More of a practical learner? You can get all of our endpoints in Postman Here -> To use some of the POST endpoints please add your tmw.media API key to Collection -> Edit -> Variables -> API_KEY

Welcome to the Radio API (REST) documentation - All of the tmw.media APIs are fully REST compliant from their release. Note: This may not be correct for beta/staging versions.

Ratelimits

API v3 introduced ratelimiting to our API - however it was a little too harsh for a radio API that is meant to be hit a lot - we have recently updated the API to now allow more requests.

Window time: 15 minutes Max Requests per 15 minutes: 1800 Delay Time: 0 - You can send messages without delays.

Errors

All errors we return will come with a description - this should help you repair the issue. These are the most common errors:

` NO_QUERY - An endpoint that requires at least one query didn't get it's query - check the docs.

FAILED_RECENT_LOOKUP - You didn't provide a number to recents or you caught the API at a bad time - try again.

INVALID_REQUEST - You're missing some queries from your request. `

States

REQUEST_SENT - Your song/shoutout request sent correctly.

Versions

API V4 introduces versioning to stop breaking changes from breaking your code in the future.

You have two choices when using our API:

Provide the version number:

api.tmw.media/v4/ggradio/song

Don't provide the version:

api.tmw.media/ggradio/song

If a version number isn't provided you will be defaulted to our "production" version (i.e version 4).

We may put a new API version into testing first where our "production" version is 4.0 for example and we are running /v5 for testing. After testing production would become v5. You may change your software version number at any time and it's recommended that you set a version number if you don't plan to update your code in the future to fit our new API structure.

If a new api version goes into production (for example /v5) it has already been tested to be stable so you may implement it right away, check https://api.tmw.media/versions first.

Modals

These modals appear at different parts of the API and will always be the same, making it easier for you to handle.

Song/Live Modal

The song or 'live' modal is always the same and contains the currently playing information: Here's an example:

"live": { "presenter": "AutoDJ", "song": "Clean Bandit - I Miss You (feat. Julia Michaels) ", "title": "I Miss You (feat. Julia Michaels) ", "artist": "Clean Bandit" }

Endpoints

These are all of the REST API endpoints we have:

Note: Most of these endpoints contain a "station" variable that you can define to chose your radio station.

Note: If you don't plan to update your code often it's recommended that you add a version to your API calls, please see above.

/station/aggregates

The aggregates endpoint contains a pre-defined list of objects you may want to use, it contains: "live" which is the currently playing song (MODAL) "recent" Which shows the 4 most recently played songs along with their artwork URL, time of play (ISO Time) and "modal" which is the SONG/LIVE MODAL shown above.

Finally, the gateway & artwork URLs are displayed at the bottom.

Aggregates may also accept the objects query on the URL allowing you to select which parts you want from aggregates

Your options are:

live, gateway, artwork, recent

Provide these arguments as a comma separated array on the objects query

For example:

api.tmw.media/ggradio/aggregates?objects=live,artwork

Note: If you request any objects that are invalid, you will you a caution message included in your response "Invalid entry, [your invalid object]"

Feel free to request this in your browser for help writing your software.

/station/[direct]

Covers: song,presenter,title,artist

These endpoints will give direct elements from the SONG/LIVE modal, these endpoints are seen as legacy, aggregates should be used most of the time.

You will receive a JSON object with your requested value.

/station/artwork

This endpoint will send you a direct image of the current artwork, feel free to place this in images as the src for example.

If you require the actual image file, you can get it from /station/artworkLookup where you are returning a JSON object with the currently active artwork URL. Direct artwork URLs are also sent in recently_played modals.

/station/recently_played

This endpoint will return X number of recently played songs

Note our limit is 20 recent songs.

Specify the query "songs" with your request set to a number 0-20 and you'll get a JSON object with the amount of recently played songs you requested.

Please note, sometimes we can't get the artwork for a song, in this case we will send the URL for the GGRadio logo, that is https://cdn.tmw.media/ggradio/images/logos/icon.png

/station/gateway

This is a simple endpoint that returns our current websocket address, if you wish to use our WebSocket, please see the documentation for it on the right.

/station/versions

This endpoint will give you the production (no version specified) and available versions for the REST and WebSocket servers.

POST /station/request

This endpoint allows you to send requests to our presenters, make a post request in the JSON content-type supplying the following information:

{"source": "Your App Name", "name": "Name of the person that sent it", "message": "Their message": "category": "request,shoutout,message,other", "avatar_url": "URL of the persons avatar"}

Please note, avatar_url is optional.

If you have any issues using our API please join our Discord server: https://discord.gg/4PfhshZ or visit our website tmw.media for contact details.

Last Updated by Cameron Fleming (Nevexo) - Systems backend engineer.

We're busy updating our API Documentation to our V4 standard, we're sorry if any information is currently missing.

Clone this wiki locally
You can’t perform that action at this time.