Integrating with Aiir's Now Playing API

Most commonly used automation systems can integrate directly with Aiir to send metadata. You can set this up in the Stations app on the Aiir platform, on the Now Playing page.

Systems which supply now playing metadata without a dedicated integration with the Aiir platform can send it to an HTTP endpoint.

Endpoint

https://api.aiir.net/v1/services/StationID/now-playing

Replace StationID with the numeric ID of your station, shown in the Aiir platform's Stations app, after you choose the 'Other' automation system type.

The endpoint supports both POST and GET requests. For POST requests, send the body as either JSON or form URL encoding. The Content-Type header should then be set accordingly, to either application/json or application/x-www-form-urlencoded.

If a parameter is supplied in both the query string and the body, the body value will be used.

Authentication

Every request must be authenticated using the StationID and password. You can find these in the Stations app in Aiir.

If you can use HTTP Basic authentication, first Base64 encode the string StationID:password, then use the result of that in an Authorization header:

Authorization: Basic Base64StationID:password

Alternatively, you can send the password in plain text in a password parameter.

Request parameters

The following parameters need to be included, either in the post body or by appending them to the URL in a query string:

`artist`	Artist of the currently playing item.
`title`	Title of the currently playing item.
`artwork_url` (Optional)	Publicly accessible URL to provide your own album artwork, replacing the image we source from Apple Music.
`type` (Optional)	Defaults to `song`. Set to `misc` to indicate the currently playing item is not a song, returning Aiir's player to display info for the current program instead.

Response codes

`200`	Accepted.
`400`	Invalid StationID, unknown station, or no recognisable data in the request.
`401`	Authentication failed.

Filtering

We'll ignore any songs that are sent if any of the following are true:

the artist or title are missing
the artist is Unknown
the title ends in .mp3

These usually indicate a misconfigured playout system sending filenames or placeholder values rather than real metadata. If your now playing data isn't appearing, this is the first thing to check.

Duplicate events are also filtered out. We compare each incoming event with the last one received for your station and ignore any data that matches the previous event.

Troubleshooting

Every request we receive is available to view in the Stations app, including requests that fail authentication or that we can't parse.

You can view the raw query string, body and headers of the most recent request there, along with a description of why authentication failed if applicable.

This is the quickest way to confirm your automation system is actually reaching us and to see exactly what it's sending.

You can access this by going to Stations > Now playing > What did Aiir receive last?