Search people

GET/v1/search/people

No API keyRate-limited

Finds people by username or display name: an exact username first, then usernames that start with the query, then the rest. Only people who chose to be discoverable are found.

Parameters#

Query parameters#

Name	Type	Description
qrequired	string	At least two characters. A leading `@` is ignored. Example: `kyle`
limit	integer default 25	How many items to return. Default 25, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.

Try it#

Sends a real request to the production API through this site. No credentials are used, so you see exactly what anyone would.

Request#

curl "https://api.rankdmusic.app/v1/search/people?q=kyle"

const response = await fetch('https://api.rankdmusic.app/v1/search/people?q=kyle');
const body = await response.json();

if (!response.ok) {
  const code = typeof body.error === 'string' ? body.error : body.error.code;
  throw new Error(`Rankd API ${response.status}: ${code}`);
}

const { data, meta } = body;

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/search/people?q=kyle")!
let (data, response) = try await URLSession.shared.data(from: url)

guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
    throw URLError(.badServerResponse)
}

let body = try JSONSerialization.jsonObject(with: data) as? [String: Any]
let result = body?["data"]

import requests

response = requests.get("https://api.rankdmusic.app/v1/search/people?q=kyle", timeout=10)
body = response.json()

if not response.ok:
    error = body["error"]
    raise RuntimeError(error if isinstance(error, str) else error["code"])

data = body["data"]

Response#

A successful response is { "data": …, "meta": … }. data is an array of PersonResult objects, and meta is a Meta.

Field	Type	Description
usernamealways	string	Username.
displayName	string	Display name, or the username when they have none.
avatarUrl	string or null	Profile picture.
ratingCount	integer	How many ratings they have made.

Responses#

200Matching people.

Captured from production: GET /v1/search/people?q=kyle&limit=5

200 response

{
  "data": [
    {
      "username": "kyle",
      "displayName": "kyle",
      "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4",
      "ratingCount": 725
    }
  ],
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400q is shorter than two characters.

Captured from production: GET /v1/music/search?q=a

400 response

{
  "error": {
    "code": "invalid_query",
    "message": "Search for at least two characters."
  }
}

429Too many requests this minute. Wait Retry-After seconds, then try again.

Headers: Retry-After Seconds to wait. Always 60.

429 response

{
  "error": "rate limited"
}