Skip to main content
GET
/
royalty
/
top-movers
Get top gainers and losers vs the previous period
curl --request GET \
  --url https://api.royalti.io/royalty/top-movers \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.royalti.io/royalty/top-movers"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.royalti.io/royalty/top-movers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.royalti.io/royalty/top-movers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.royalti.io/royalty/top-movers"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.royalti.io/royalty/top-movers")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.royalti.io/royalty/top-movers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "dimension": "dsp",
  "gainers": [
    {
      "DSP": "Spotify",
      "Royalty": 2456.75,
      "Count": 245000,
      "RoyaltyPercentage": 12.5,
      "CountPercentage": 8.2,
      "RatePer1K": 10.03,
      "PreviousRoyalty": 2183.15,
      "PreviousCount": 226300,
      "DeltaRoyalty": 273.6,
      "DeltaPct": 12.5
    }
  ],
  "losers": [
    {
      "DSP": "YouTube Music",
      "Royalty": 1102.25,
      "Count": 98000,
      "RoyaltyPercentage": -2.1,
      "CountPercentage": -1.5,
      "RatePer1K": 11.25,
      "PreviousRoyalty": 1125.13,
      "PreviousCount": 99470,
      "DeltaRoyalty": -22.88,
      "DeltaPct": -2.1
    }
  ]
}
This endpoint requires authentication. Include your Bearer token in the Authorization header.

Description

Get top gainers and losers vs the previous period Ranks dimension values (assets, products, artists, DSPs, countries, sale types, or aggregators) by the change in royalty between the requested period and the equal-length prior period, returning the top gainers and top losers separately. Requires a bounded period: pass start (and optionally end). If start is omitted, the endpoint returns an empty gainers/losers pair with an explanatory message instead of an error. Authorization:
  • Required role: user or higher

Code Examples

const response = await fetch('https://api.royalti.io/royalty/top-movers', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const data = await response.json();
console.log(data);
import requests

response = requests.get(
  'https://api.royalti.io/royalty/top-movers',
  headers={
    'Authorization': f'Bearer {token}'
  },
)

data = response.json()
print(data)
curl -X GET https://api.royalti.io/royalty/top-movers \
  -H "Authorization: Bearer YOUR_TOKEN" \

Authorizations

Authorization
string
header
required

JWT Authorization header using the Bearer scheme. Format: "Bearer {token}"

Query Parameters

dimension
enum<string>
default:asset

Dimension to rank movers by. Defaults to (and falls back to) asset for an omitted/invalid value.

Available options:
dsp,
country,
artist,
asset,
product,
saletype,
aggregator
n
integer
default:10

Number of gainers and number of losers to return. Clamped to 1-50.

Required range: 1 <= x <= 50
artists
string

Filters the data by artist. Comma-separated list of artist IDs

user
string<uuid>

Filters the data by user. Specifies a user ID. A single UUID switches the response into per-member (splits-attributed) mode

country
string

Filter the data by country. Comma-separated values

dsp
string

Filters by DSP (Digital Service Provider). Comma-separated values

start
string<date>
required

Start date of the current period (YYYY-MM-DD format). Required — this endpoint needs a bounded period to compute deltas against the equal-length prior period

end
string<date>

End date of the period (YYYY-MM-DD format)

type
string

Filters by sale type. Comma-separated values

aggregator
string

Filters by aggregator. Comma-separated values

table_name
string

Filters by data source table name. Comma-separated values for multiple tables

upc
string

Filters by UPC (Universal Product Code). Comma-separated values

isrc
string

Filters by ISRC (International Standard Recording Code). Comma-separated values

periodFilterType
enum<string>

Filters by either 'accounting' or 'sale' period

Available options:
accounting,
sale

Response

Successfully retrieved top movers (or an empty pair with message if no bounded period was given)

dimension
enum<string>

Dimension the movers were grouped by. Defaults to (and falls back to) asset for an omitted/invalid value

Available options:
dsp,
country,
artist,
asset,
product,
saletype,
aggregator
gainers
object[]
losers
object[]