#Leaderboards API

The Leaderboards API provides access to game rankings and statistics for players across various categories.

#Endpoint

GET /v2/leaderboards

#Authentication

All requests require the X-API-Key header. See Authentication for details.

#Query Parameters

You must specify at least one leaderboard type parameter. Multiple leaderboard types can be requested in a single call.

#Response

#Leaderboard Entry

{
  name: string;
  value: number;
  rank: number;
}

#Response Structure

The response is an object with keys for each requested leaderboard type, containing arrays of leaderboard entries:

{
  [leaderboardType: string]: Array<{
    name: string;
    value: number;
    rank: number;
  }>;
}

#Examples

#Get Credits Leaderboard

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/leaderboards?credits=true"

Response:

{
  "credits": [
    {
      "name": "PlayerOne",
      "value": 150000,
      "rank": 1
    },
    {
      "name": "PlayerTwo",
      "value": 125000,
      "rank": 2
    },
    {
      "name": "PlayerThree",
      "value": 100000,
      "rank": 3
    }
  ]
}

#Get Multiple Leaderboards

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/leaderboards?credits=true&combatsWon=true&highestLevels=true"

Response:

{
  "credits": [
    {
      "name": "PlayerOne",
      "value": 150000,
      "rank": 1
    },
    {
      "name": "PlayerTwo",
      "value": 125000,
      "rank": 2
    }
  ],
  "combatsWon": [
    {
      "name": "WarriorKing",
      "value": 500,
      "rank": 1
    },
    {
      "name": "BattleMaster",
      "value": 450,
      "rank": 2
    }
  ],
  "highestLevels": [
    {
      "name": "MaxLevel",
      "value": 99,
      "rank": 1
    },
    {
      "name": "AlmostThere",
      "value": 98,
      "rank": 2
    }
  ]
}

#Get Leaderboards for Specific User

When filtering by username, only entries for that user are returned across all requested leaderboards:

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/leaderboards?name=PlayerOne&credits=true&combatsWon=true"

Response:

{
  "credits": [
    {
      "name": "PlayerOne",
      "value": 150000,
      "rank": 1
    }
  ],
  "combatsWon": [
    {
      "name": "PlayerOne",
      "value": 325,
      "rank": 5
    }
  ]
}

#Get All Available Leaderboards

curl -H "X-API-Key: YOUR_API_KEY" \
     "https://api.betweenworlds.net/v2/leaderboards?credits=true&highestLevels=true&combatsWon=true&itemsCrafted=true&jobsPerformed=true&overdoses=true&missionsCompleted=true"

#JavaScript Example

const apiKey = 'YOUR_API_KEY';

// Get multiple leaderboards
async function getLeaderboards(types) {
  const params = new URLSearchParams();

  // Add each leaderboard type
  types.forEach((type) => {
    params.append(type, 'true');
  });

  const response = await fetch(`https://api.betweenworlds.net/v2/leaderboards?${params}`, {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  return response.json();
}

// Get specific user's ranking
async function getUserRankings(userName, types) {
  const params = new URLSearchParams({
    name: userName,
  });

  types.forEach((type) => {
    params.append(type, 'true');
  });

  const response = await fetch(`https://api.betweenworlds.net/v2/leaderboards?${params}`, {
    headers: {
      'X-API-Key': apiKey,
    },
  });

  return response.json();
}

// Usage
getLeaderboards(['credits', 'combatsWon', 'highestLevels']).then((leaderboards) => console.log(leaderboards));

getUserRankings('PlayerOne', ['credits', 'combatsWon']).then((rankings) => console.log(rankings));

#Leaderboard Types

#credits

Rankings based on total credits (in-game currency) accumulated.

#highestLevels

Rankings based on character level achieved.

#combatsWon

Rankings based on total number of combat victories.

#itemsCrafted

Rankings based on total number of items crafted.

#jobsPerformed

Rankings based on total number of jobs completed.

#overdoses

Rankings based on number of overdoses (if applicable to game mechanics).

#missionsCompleted

Rankings based on total number of missions completed.

#Error Responses

#Notes

• Multiple Types: You can request multiple leaderboard types in a single API call
• At Least One Type Required: You must specify at least one leaderboard type parameter (beyond the required auth parameters)
• Name Filter: When using the name parameter, you must also specify at least one leaderboard type
• Case Sensitivity: User names are case-insensitive when filtering
• Response Keys: The response object keys match the parameter names (e.g., credits, combatsWon, etc.)

#Use Cases

• Display global rankings on websites
• Show player statistics and rankings
• Create leaderboard widgets for streaming
• Build achievement tracking tools
• Compare player performance across categories
• Generate ranking reports and analytics