Vericast API

Our Vericast API allows you to build your own interfaces or dashboards based on our music identification platform for audio recognition and broadcast monitoring.

Introduction

Access to the Vericast service is provided via a REST style interface.

The production API is located at the following address: https://api-vericast.bmat.me/1/

A successful response will have the following format:

<response status="ok"/>

An error response status  means an error has occurred while processing a request.

A failed request will contain an error message instead of the results content:

<response status="failed">
    <error code="3">
        Invalid API key - You must be granted a valid key by Vericast
    </error>
</response>

Error codes:

  • 1 : Invalid user – You must be granted a valid user account for Vericast
  • 2 : User disabled – Access to your account has been suspended, please contact Vericast
  • 3 : Invalid API key – You must be granted a valid key for Vericast
  • 4 : No method with that name in this API
  • 20 : Invalid parameter
  • 21 : Invalid dates
  • 22 : Invalid identificator for Entity
  • 23 : The Entity identificator doesn’t exist
  • 24 : Valid periods are day, week or month
  • 30 : The artist you entered could not be found
  • 31 : Track not found
  • 32 : Invalid match id

Use UTF-8 encoding when sending parameters to API methods.

Status

Get the current server time.

Example request:

https://api-vericast.bmat.me/1/status

Example response:

<servicestatus>
    <servertime>2012-12-20T17:16:45</servertime>
</servicestatus>

Artist Methods

artist/info

Get the metadata for an artist in Vericast.

Parameters:

  • name (required unless bmatid): The artist name.
  • bmatid (required unless name): The artist’s bmatid
  • User (required): The Vericast username.
  • api (required): The Vericast API key.

Example request:

https://api-vericast.bmat.me/1/artist/info?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&artist=Madonna

Example response:

<artist>
    <name>Madonna</name>
    <bmatid>2be93f3d-8c66-4225-b05b-6e1509555146</bmatid>
    <url>
      https://vericast.bmat.me/artist/2be93f3d-8c66-4225-b05b-6e1509555146
    </url>
</artist>

Channel Methods

channel/info

Get the metadata for a channel on Vericast.

Parameters:

  • channel (required): The channel keyname.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.

Example request:

https://api-vericast.bmat.me/1/channel/info?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&channel=los40-direct-url————–01

Example response:

<channel>
    <name>40 Principales</name>
    <keyname>los40-direct-url--------------01</keyname>
    <location>
        <city>Madrid (Madrid)</city>
        <country>Spain</country>
    </location>
    <url>https://vericast.bmat.me/channel/los40-direct-url--------------01</url>
    <media>Radio FM</media>
    <website>http://www.los40.com</website>
</channel>

channel/list

Get the list of channels  the user is subscribed to.

Parameters:

  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • limit (optional): The number of results to fetch per page. By default, it is set to 50.
  • page (optional): The page number to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/channel/list?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE

Example response:

<listchannels perPage="5" page="5">
  <channel>
      <name>40 Principales</name>
      <keyname>los40-direct-url--------------01</keyname>
      <location>
          <city>Madrid (Madrid)</city>
          <country>Spain</country>
      </location>
      <url>https://vericast.bmat.me/channel/los40-direct-url--------------01</url>
      <media>Radio FM</media>
      <website>http://www.los40.com</website>
  </channel>
    ...
</listchannels>

Charts Methods

charts/topartists

Get the top artists chart, ordered by playcount.

Parameters:

  • period (optional): The time period that you generate the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart, the default value is set to the date previous to the current one.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • channel (optional): The channel keyname.
  • label (optional): The label name.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The page number of which page to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/charts/topartists?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<topartists perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <artist>
      <name>Madonna</name>
      <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
      <url>https://vericast.bmat.me/artist/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
      <playcount>44</playcount>
  </artist>
  ...
</topartists>

charts/topchannels

Get the top channels chart, ordered by playcount.

Parameters:

  • period (optional): The time period you are generating the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart, the default value is set to the date previous to the current one.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • artist_bmatid (optional): The artist bmatid.
  • artist_name (optional): The artist name.
  • track_bmatid (optional): The track bmatid.
  • isrc (optional): The track ISRC.
  • label (optional): The label name.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/charts/topchannels?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<topachannels perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <channel>
      <name>Mega 98.3</name>
      <keyname>mega--------------------------01</keyname>
      <url>https://vericast.bmat.me/channel/mega--------------------------01></url>
      <playcount>2</playcount>
  </channel>
  ...
</topchannels>

charts/toplabels

Get the top labels chart, ordered by playcount.

Parameters:

  • period (optional): The time period you are generating the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart, the default value is set to the date previous to the current one.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • channel (optional): The channel keyname.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/charts/toplabels?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<toplabels perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <label>
      <name>Sony Music Entertainment</name>
      <playcount>311</playcount>
  </label>
  ...
</toplabels>

charts/toptracks

Get the top tracks chart, ordered by playcount.

Parameters:

  • period (optional): The time period you are generating the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart, the default value is set to the date previous to the current one.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • artist_bmatid (optional): The artist bmatid.
  • artist_name (optional): The artist name.
  • channel (optional): The channel keyname.
  • label (optional): The label name.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.
  • showfcf (optional): Show the FCF (Unknowns tracks) if true. By default it is set to false.

Example request:

https://api-vericast.bmat.me/1/charts/toptracks?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<toptracks perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <track>
      <name>Girl Gone Wild</name>
      <phonogram_bmatid>d38e2a8b-576e-416c-ad98-bd0d0569a6b5</phonogram_bmatid>
      <track_bmatid>0167d560-b53a-495d-af18-359dfd0d868</track_bmatid>
      <bmatid>0167d560-b53a-495d-af18-359dfd0d8685</bmatid>
      <url>https://vericast.bmat.me/track/0167d560-b53a-495d-af18-359dfd0d868</url>
      <isrc>US-S1Z-99-00001</isrc>
      <artist>
          <name>Madonna</name>
          <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
          <url>https://vericast.bmat.me/artist/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
      </artist>
      <label>
          <name>Sony Music Entertainment</name>
          <url>https://vericast.bmat.me/label/Sony+Music+Entertainment</url>
      </label>
      <playcount>123</playcount>
      <additional-fields>
        <additional-field>
          <name>Custom ID</name>
          <value>4D696C6C696F6E20446F6C6C61722042696C6C</value>
        </additional-field>
      </additional-fields>
  </track>
  ...
</toptracks>

charts/fcfresolveds

Get the unknown tracks that have been resolved.

Parameters:

  • period (optional): The time period you are generating the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart, the default value is set to the date previous to the current one.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/charts/fcfresolveds?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<fcfresolveds perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <resolved>
    <old_bmatid>0167d560-b53a-495d-af18-359dfd0d8685</old_bmatid>
    <unknown_id>324123</unknown_id>
    <log_date>2014-10-22 10:00:00</log_date>
    <autoedit>1</autoedit>
    <name>Girl Gone Wild</name>
    <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
    <url>https://vericast.bmat.me/track/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
    <artist>
        <name>Madonna</name>
        <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
        <url>https://vericast.bmat.me/artist/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
    </artist>
    <label>
        <name>Sony Music Entertainment</name>
        <url>https://vericast.bmat.me/label/Sony+Music+Entertainment</url>
    </label>
  </resolved>
  ...
</fcfresolveds>

Label Methods

label/info

Get the metadata for a label in Vericast.

Parameters:

  • name (required): The label name.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.

Example request:

https://api-vericast.bmat.me/1/label/info?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&name=Universal%20Music%20Group

Example response:

<label>
  <name>Universal Music Group</name>
  <url>
    https://vericast.bmat.me/label/Universal+Music+Group
  </url>
</label>

Match Methods

match/info

Get the metadata for a match in Vericast.

Parameters:

  • match (required): The numeric Vericast match id.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.

Example request:

https://api-vericast.bmat.me/1/match/info?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&match=420262

Example response:

<match>
    <id>420262</id>
    <datetime>2011-06-06T22:05:09+00:00</datetime>
    <duration>17</duration>
    <channel>
        <name>La 100</name>
        <keyname>lr6-la-cien-fm-99-9-----------01</keyname>
        <url>https://vericast.bmat.me/channel/lr6-la-cien-fm-99-9-----------01</url>
    </channel>
    <track>
        <name>Girl Gone Wild</name>
        <phonogram_bmatid>d38e2a8b-576e-416c-ad98-bd0d0569a6b5</phonogram_bmatid>
        <track_bmatid>0167d560-b53a-495d-af18-359dfd0d868</track_bmatid>
        <bmatid>0167d560-b53a-495d-af18-359dfd0d868</bmatid>
        <url>https://vericast.bmat.me/track/0167d560-b53a-495d-af18-359dfd0d868</url>
        <isrc>US-S1Z-99-00001</isrc>
        <label>Sony Music Entertainment</label>
        <artist>
            <name>Madonna</name>
            <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
            <url>https://vericast.bmat.me/artist/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
        </artist>
        <additional-fields>
          <additional-field>
            <name>Custom ID</name>
            <value>4D696C6C696F6E20446F6C6C61722042696C6C</value>
          </additional-field>
        </additional-fields>
    </track>
</match>

match/list

Get all matches ordered by datetime.

Parameters:

  • period (optional): The time period you are generating the chart for (day, week, month). By default it is set to week.
  • end (optional): The last day with data included in the chart includes data for, the default value is set to the date previous to the current one.
  • artist_bmatid (optional): The artist bmatid.
  • artist_name (optional): The artist name.
  • track_bmatid (optional): The track bmatid.
  • isrc (optional): The track ISRC.
  • channel (optional): The channel keyname.
  • label (optional): The label name.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • limit (optional): The number of results to fetch per page. The default is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.
  • showfcf (optional): Show the FCF (Unknowns tracks) if true. By default it is set to false.
  • cf (optional): Custom fields. Filter by pair’s name:value, ex. myid:12333

Example request:

https://api-vericast.bmat.me/1/match/list?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week

Example response:

<matches perPage="50" page="1" start="2011-06-01" end="2011-06-07">
  <match>
      <id>420260</id>
      <datetime>2011-06-06T22:05:09+00:00</datetime>
      <duration>17</duration>
      <channel>
          <name>La 100</name>
          <keyname>lr6-la-cien-fm-99-9-----------01</keyname>
          <url>https://vericast.bmat.me/channel/lr6-la-cien-fm-99-9-----------01</url>
      </channel>
      <track>
          <name>Girl Gone Wild</name>
          <phonogram_bmatid>d38e2a8b-576e-416c-ad98-bd0d0569a6b5</phonogram_bmatid>
          <track_bmatid>0167d560-b53a-495d-af18-359dfd0d868</track_bmatid>
          <bmatid>0167d560-b53a-495d-af18-359dfd0d868</bmatid>
          <url>https://vericast.bmat.me/track/0167d560-b53a-495d-af18-359dfd0d868</url>
          <isrc>US-S1Z-99-00001</isrc>
          <iswc>US-S2W-99-00001<iswc/>
          <artist>
              <name>Madonna</name>
              <bmatid>065bc8fb-9935-4fe8-b782-6c2eb9fffa53</bmatid>
              <url>https://vericast.bmat.me/artist/065bc8fb-9935-4fe8-b782-6c2eb9fffa53</url>
          </artist>
          <album>MDNA</album>
          <catalog>Anglo</catalog>
          <label>
              <name>Sony Music Entertainment</name>
              <url>https://vericast.bmat.me/label/Sony+Music+Entertainment</url>
          </label>
          <additional-fields>
            <additional-field>
              <name>Custom ID</name>
              <value>4D696C6C696F6E20446F6C6C61722042696C6C</value>
            </additional-field>
            <additional-field>
                <name>tags</name>
                <value>MYTAG1,MYTAG2</value>
            </additional-field>
          </additional-fields>
      </track>
      <program>
        <title>A League of Their Own: US Road Trip</title>
        <category>Other</category>
        <type>Non Commercial</type>
        <production_company>Virtual Studios</production_company>
      </program>
  </match>
  ...
</matches>

Multiple values & priorities:

Note that artist_bmatid, artist_name, track_bmatid, isrc, channel and label parameters accept multiple values. To get these, just concatenate multiple key-value pairs. This will be treated as an OR statement, meaning that it will show the results of ANY of the provided values.

Example: Multiple artists names.

This will return all matches for artist Madonna, plus all matches for artist The Beatles

https://api-vericast.bmat.me/1/match/list?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week&artist_name=Madonna&artist_name=The%Beatles

However, using multiple parameters will be treated as an AND statement, meaning that this will give results that match ALL of the provided values.

Example: One artists name, one label

This will return empty results. There are no tracks for artist Madonna with label Universal Music Group

https://api-vericast.bmat.me/1/match/list?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&end=20110607&period=week&artist_name=Madonna&label=Universal%Music%Group

track/info

Get the metadata for a track in Vericast.

Parameters:

  • bmatid (optional): The track bmatid.
  • isrc (optional): The track ISRC.
  • artist (required unless bmatid or isrc): The artist name.
  • track (required unless bmatid or isrc): The track name.
  • user (required): The Vericast username.
  • api (required): The Vericast API key.

Example request:

https://api-vericast.bmat.me/1/track/info?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&isrc=GBAYE9901224

Example response:

<track>
    <name>Sgt. Pepper'S Lonely Hearts Club Band</name>
    <phonogram_bmatid>6c2659fc-9be6-4e2b-b2b3-467577c37e05</phonogram_bmatid>
    <track_bmatid>42005e92-aacd-4b72-a994-3348d437b7e6</track_bmatid>
    <bmatid>42005e92-aacd-4b72-a994-3348d437b7e6</bmatid>
    <url>
        https://vericast.bmat.me/track/42005e92-aacd-4b72-a994-3348d437b7e6
    </url>
    <isrc>GBAYE9901224</isrc>
    <iswc/>
    <artist>
        <name>The Beatles</name>
        <bmatid>8a92be34-c7b7-4c72-83f5-154fc63df57c</bmatid>
        <url>
            https://vericast.bmat.me/artist/8a92be34-c7b7-4c72-83f5-154fc63df57c
        </url>
    </artist>
    <album>Yellow Submarine</album>
    <label>
        <name>EMI Records Ltd/Apple Corps Ltd</name>
        <url>
            https://vericast.bmat.me/label/EMI+Records+Ltd%2FApple+Corps+Ltd
        </url>
    </label>
    <additional-fields/>
</track>

track/search

Search the tracks with a query term. Search in artist and track name.

Parameters:

  • q (required): The query to search
  • user (required): The Vericast username.
  • api (required): The Vericast API key.
  • limit (optional): The number of results to fetch per page. By default it is set to 50.
  • page (optional): The number of pages to fetch. By default it is set to the first page.

Example request:

https://api-vericast.bmat.me/1/track/search?user=YOUR_USERNAME_HERE&api=YOUR_KEY_HERE&q=Metallica

Example response:

<searchtracks perPage="50" page="1">
    <track>
        <name>The Day That Never Comes</name>
        <phonogram_bmatid>d38e2a8b-576e-416c-ad98-bd0d0569a6b5</phonogram_bmatid>
        <track_bmatid>0167d560-b53a-495d-af18-359dfd0d868</track_bmatid>
        <bmatid>d9bebd36-677c-42cf-8f08-1bb6853066d9</bmatid>
        <url>https://vericast.bmat.me/track/d9bebd36-677c-42cf-8f08-1bb6853066d9</url>
        <artist>
            <name>Metallica</name>
            <bmatid>382fd9c9-43ee-47d0-a29e-8324315ef89b</bmatid>
            <url>https://vericast.bmat.me/artist/382fd9c9-43ee-47d0-a29e-8324315ef89b</url>
        </artist>
        <label>
            <name>Universal Music Group</name>
            <url>https://vericast.bmat.me/label/Universal+Music+Group</url>
        </label>
        <additional-fields>
          <additional-field>
            <name>Custom ID</name>
            <value>4D696C6C696F6E20446F6C6C61722042696C6C</value>
          </additional-field>
        </additional-fields>
    </track>