Introduction Status Artist info Channel info Channel list Charts daily Charts top artists Charts top channels Charts top labels Vericast API (1.0.0) Download OpenAPI specification:Download E-mail: sw-vericast@bmat.com License: Apache 2.0 Introduction Our Vericast API allows you to build your own interfaces or dashboards based on our music identification platform for audio recognition and broadcast monitoring. Access to the Vericast service is provided via a REST style interface. The production API is kept here Vericast API In case of any doubt, contact us at hello@bmat.com. RESPONSES Once you have your personal access token, you can start making requests. 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 element instead of the results content: <response status="failed"> <error code="3"> Invalid API key - You must be granted a valid key for Vericast </error> </response> Error codes 1 : Invalid user - You must be granted a valid user 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 arguments to API methods. If the user doesn’t have additional fields, this tag will be empty in all the tracks. Status Quickly check the API status Responses 200 Get the current server time. GET /status Response samples 200 Content type application/xml Copy { "servertime": "<servicestatus>\n <servertime>2012-12-20T17:16:45</servertime>\n</servicestatus>\n" } Artist info Get the metadata for an artist on Vericast Get the metadata for an artist on Vericast QUERY PARAMETERS artist string Example: artist=Madonna The artist name (required unless bmatid). bmatid string Example: bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist's bmatid (required unless bmatid). user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. Responses 200 Artist info successfully retrieved GET /artist/info Response samples 200 Content type application/xml Copy <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 info Get the metadata for a channel on Vericast. Get the metadata for a channel on Vericast. QUERY PARAMETERS channel required string Example: channel=los40-direct-url--------------01 The channel keyname. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. Responses 200 Channel info successfully retrieved GET /channel/info Response samples 200 Content type application/xml Copy <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 Get the list of channels the user is subscribed to. QUERY PARAMETERS user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Channel list successfully retrieved GET /channel/list Response samples 200 Content type application/xml Copy <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 daily Get daily stats including plays and impact (when a Get daily stats including plays and impact (when accessible by the user). The results can be filtered by (m)any of the available params. QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. channel string Example: channel=los40-direct-url--------------01 The channel keyname. country string Example: country=es The channel country code ISO_3166-1_alpha-2. media_type string Enum: "Radio FM" "Radio AM" "TV" "Venues" The channel’s media type. artist_bmatid string Example: artist_bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist bmatid. artist_name string Example: artist_name=Madonna The artist name. isrc string Example: isrc=US-S1Z-99-00001 The track ISRC. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Daily chart successfully retrieved GET /charts/daily Response samples 200 Content type application/xml Copy <daily page="1" perPage="50"> <stat> <date>2019-07-01</date> <plays>112271</plays> </stat> <stat> <date>2019-07-02</date> <plays>111209</plays> </stat> <stat> <date>2019-07-03</date> <plays>111066</plays> </stat> <stat> <date>2019-07-04</date> <plays>111459</plays> </stat> <stat> <date>2019-07-05</date> <plays>110798</plays> </stat> <stat> <date>2019-07-06</date> <plays>115520</plays> </stat> <stat> <date>2019-07-07</date> <plays>108366</plays> </stat> </daily> Charts top artists Get the top artists chart, ordered by playcount. Get the top artists chart, ordered by playcount. QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. channel string Example: channel=los40-direct-url--------------01 The channel keyname. country string Example: country=es The channel country code ISO_3166-1_alpha-2. media_type string Enum: "Radio FM" "Radio AM" "TV" "Venues" The channel’s media type. label string Example: label=Sony Music Entertainment The label name. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Top artists chart successfully retrieved GET /charts/topartists Response samples 200 Content type application/xml Copy <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> <plays>44</plays> <playtime>70115</playtime> </artist> ... </topartists> Charts top channels Get the top channels chart, ordered by playcount. Get the top channels chart, ordered by playcount. QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. artist_bmatid string Example: artist_bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist bmatid. artist_name string Example: artist_name=Madonna The artist name. track_bmatid string Example: track_bmatid=0167d560-b53a-495d-af18-359dfd0d868 The track bmatid. isrc string Example: isrc=US-S1Z-99-00001 The track ISRC. label string Example: label=Sony Music Entertainment The label name. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Top channels chart successfully retrieved GET /charts/topchannels Response samples 200 Content type application/xml Copy <topachannels perPage="50" page="1" start="2011-06-01" end="2011-06-07"> <channel> <name>Mega 98.3</name> <keyname>mega--------------------------01</keyname> <location> <country>Spain</country> <country_code>es</country_code> <city>Madrid</city> </location> <url>https://vericast.bmat.me/channel/mega--------------------------01</url> <plays>2</plays> <playtime>39</playtime> </channel> ... </topchannels> Charts top labels Get the top labels chart, ordered by playcount. Get the top labels chart, ordered by playcount. QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. channel string Example: channel=los40-direct-url--------------01 The channel keyname. media_type string Enum: "Radio FM" "Radio AM" "TV" "Venues" The channel’s media type. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Top labels chart successfully retrieved GET /charts/toplabels Response samples 200 Content type application/xml Copy <toplabels perPage="50" page="1" start="2011-06-01" end="2011-06-07"> <label> <name>Sony Music Entertainment</name> <plays>311</plays> <playtime>3927</playtime> </label> ... </toplabels> Charts top tracks Get the top tracks chart, ordered by playcount. Get the top tracks chart, ordered by playcount. QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. artist_bmatid string Example: artist_bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist bmatid. artist_name string Example: artist_name=Madonna The artist name. channel string Example: channel=los40-direct-url--------------01 The channel keyname. country string Example: country=es The channel country code ISO_3166-1_alpha-2. media_type string Enum: "Radio FM" "Radio AM" "TV" "Venues" The channel’s media type. label string Example: label=Sony Music Entertainment The label name. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. showfcf string Example: showfcf=false Show the FCF (Unknowns tracks) if true. By default, it is set to false. Responses 200 Top tracks chart successfully retrieved GET /charts/toptracks Response samples 200 Content type application/xml Copy <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> <plays>123</plays> <playtime>5741</playtime> <additional-fields> <additional-field> <name>Custom ID</name> <value>4D696C6C696F6E20446F6C6C61722042696C6C</value> </additional-field> </additional-fields> </track> ... </toptracks> Chart FCF resolved Get the unknown tracks that have been resolved Get the unknown tracks that have been resolved QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 FCF resolved chart successfully retrieved GET /charts/fcfresolved Response samples 200 Content type application/xml Copy <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 info Get the metadata for a label in Vericast. Get the metadata for a label in Vericast. QUERY PARAMETERS label required string Example: label=Sony Music Entertainment The label name. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. Responses 200 Label info successfully retrieved GET /label/info Response samples 200 Content type application/xml Copy <label> <name>Universal Music Group</name> <url> https://vericast.bmat.me/label/Universal+Music+Group </url> </label> Match info Get the metadata for a match in Vericast. Get the metadata for a match in Vericast. QUERY PARAMETERS match required string Example: match=420262 The numeric Vericast match id. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. Responses 200 Match info successfully retrieved GET /match/info Response samples 200 Content type application/xml Copy <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> <location> <country>Spain</country> <country_code>es</country_code> <city>Madrid</city> </location> </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. Note that ar Get all matches ordered by datetime. Note that artist_bmatid, artist_name, track_bmatid, isrc, channel and label parameters accept multiple values. To achieve this, just concatenate multiple key-value pairs. This will be treated as an OR statement, meaning that will give results for ANY of the provided values. Example: Multiple artits 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 will give results that match ALL 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 QUERY PARAMETERS period string Enum: "day" "week" "month" The time period that you generate the chart for. By default, it is set to week. When month is selected, results will show starting day 1st of the month in the query. end string <YYYYMMDD> Example: end=20210201 The last day twith data included in the chart. The default value is set to the date previous to the current one. artist_bmatid string Example: artist_bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist bmatid. artist_name string Example: artist_name=Madonna The artist name. track_bmatid string Example: track_bmatid=0167d560-b53a-495d-af18-359dfd0d868 The track bmatid. isrc string Example: isrc=US-S1Z-99-00001 The track ISRC. channel string Example: channel=los40-direct-url--------------01 The channel keyname. label string Example: label=Sony Music Entertainment The label name. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. showfcf string Example: showfcf=false Show the FCF (Unknowns tracks) if true. By default, it is set to false. cf string Example: cf=Custom ID:4D696C6C696F6E20446F6C6C61722042696C6C Custom fields. Filters by pairs name:value, ex. myid:12333 catalog string Example: catalog=Anglo Catalog name to filter by. Responses 200 Match list successfully retrieved GET /match/list Response samples 200 Content type application/xml Copy <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> <location> <country>Spain</country> <country_code>es</country_code> <city>Madrid</city> </location> </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> Track info Get the metadata for a track in Vericast. Get the metadata for a track in Vericast. QUERY PARAMETERS bmatid string Example: bmatid=2be93f3d-8c66-4225-b05b-6e1509555146 The artist's bmatid (required unless bmatid). isrc string Example: isrc=US-S1Z-99-00001 The track ISRC. artist required string Example: artist=The Beatles The artist name (required unless bmatid or isrc). track required string Example: track=Sgt. Pepper'S Lonely Hearts Club Band The track name (required unless bmatid or isrc). user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. Responses 200 Track info successfully retrieved GET /track/info Response samples 200 Content type application/xml Copy <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 by a query term. Search in artis Search the tracks by a query term. Search in artist and track name QUERY PARAMETERS q required string Example: q=Metallica The query to search. user required string Example: user=YOUR_USER_NAME The Vericast username. api required string Example: api=1f27as12h1 The Vericast API key. limit integer Example: limit=50 The number of results to fetch per page. By default, it is set to 50. page integer Example: page=1 The page number to fetch. By default, it is set to first page. Responses 200 Search track by a query term successfully retrieved. GET /track/search Response samples 200 Content type application/xml Copy <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> </searchtracks>