# Hiscores

## Usage

```python
from rs3_api import Hiscores
hiscore = Hiscores()
```

## Functions

### get\_ranking(index: int, category: str, size: int)

> Gets hiscore ranks in a particular skill or activity

| Parameters | Type                | default |
| ---------- | ------------------- | ------- |
| `index`    | `int`               |         |
| `category` | `skill \| activity` | `skill` |
| `size`     | `int`               | `25`    |

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_ranking(0, "skill", 10)
print(response)
```

{% endtab %}

{% tab title="Response" %}

```python
{
  'category': 'overall',
  'rankings': [
    {
      'name': 'le me',
      'score': '5,600,000,000',
      'rank': '1'
    },
    {
      'name': 'L33',
      'score': '5,600,000,000',
      'rank': '2'
    },
    {
      'name': 'Omid',
      'score': '5,600,000,000',
      'rank': '3'
    },
    {
      'name': 'Maikeru',
      'score': '5,600,000,000',
      'rank': '4'
    },
    {
      'name': 'iTrolledU',
      'score': '5,600,000,000',
      'rank': '5'
    },
    {
      'name': 'Ai',
      'score': '5,600,000,000',
      'rank': '6'
    },
    {
      'name': 'Randles',
      'score': '5,600,000,000',
      'rank': '7'
    },
    {
      'name': 'Wai',
      'score': '5,600,000,000',
      'rank': '8'
    },
    {
      'name': 'Jose Return',
      'score': '5,600,000,000',
      'rank': '9'
    },
    {
      'name': 'E',
      'score': '5,600,000,000',
      'rank': '10'
    }
  ]
}
```

{% endtab %}

{% tab title="Index" %}

```python
SKILLS = [
    "overall", # index = 0
    "attack", # index = 1
    "defence", # ...
    "strength",
    "constitution",
    "ranged",
    "prayer",
    "magic",
    "cooking",
    "woodcutting",
    "fletching",
    "fishing",
    "firemaking",
    "crafting",
    "smithing",
    "mining",
    "herblore",
    "agility",
    "thieving",
    "slayer",
    "farming",
    "runecrafting",
    "hunter",
    "construction",
    "summoning",
    "dungeoneering",
    "divination",
    "invention",
    "archaeology",
]

ACTIVITIES = [
    "bounty hunter",
    "b.h. rogues",
    "dominion tower",
    "the crucible",
    "castle wars games",
    "b.a. attackers",
    "b.a. defenders",
    "b.a. collectors",
    "b.a. healers",
    "duel tournament",
    "mobilising armies",
    "conquest",
    "fist of guthix",
    "gg: athletics",
    "gg: resource race",
    "we2: armadyl lifetime contribution",
    "we2: bandos lifetime contribution",
    "we2: armadyl pvp kills",
    "we2: bandos pvp kills",
    "heist guard level",
    "heist robber level",
    "cfp: 5 game average",
    "af15: cow tipping",
    "af15: rats killed after the miniquest",
    "runescore",
    "clue scrolls easy",
    "clue scrolls medium",
    "clue scrolls hard",
    "clue scrolls elite",
    "clue scrolls master",
]
```

{% endtab %}
{% endtabs %}

### get\_index\_lite(game\_mode: str, username: str)

> Gets a players hiscore profile

| Parameters  | Type                            |
| ----------- | ------------------------------- |
| `game_mode` | `normal \| ironman \| hardcore` |
| `username`  | `str`                           |

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_index_lite("normal", "Phyrexz")
print(response)
```

{% endtab %}

{% tab title="Response" %}

```python
{
  'name': 'Phyrexz',
  'skills': {
    'overall': {
      'rank': '241697',
      'level': '2282',
      'experience': '233272699'
    },
    'attack': {
      'rank': '180625',
      'level': '99',
      'experience': '13861825'
    },
    'defence': {
      'rank': '50002',
      'level': '99',
      'experience': '56921532'
    },
    'strength': {
      'rank': '194150',
      'level': '99',
      'experience': '13875435'
    },
    'constitution': {
      'rank': '101259',
      'level': '99',
      'experience': '38885437'
    },
    'ranged': {
      'rank': '144078',
      'level': '99',
      'experience': '16986747'
    },
    'prayer': {
      'rank': '237501',
      'level': '95',
      'experience': '9120570'
    },
    'magic': {
      'rank': '143901',
      'level': '99',
      'experience': '17240996'
    },
    'cooking': {
      'rank': '521275',
      'level': '70',
      'experience': '743947'
    },
    'woodcutting': {
      'rank': '536522',
      'level': '75',
      'experience': '1299101'
    },
    'fletching': {
      'rank': '501103',
      'level': '70',
      'experience': '771000'
    },
    'fishing': {
      'rank': '555898',
      'level': '66',
      'experience': '505967'
    },
    'firemaking': {
      'rank': '505878',
      'level': '70',
      'experience': '802511'
    },
    'crafting': {
      'rank': '299668',
      'level': '81',
      'experience': '2241028'
    },
    'smithing': {
      'rank': '372296',
      'level': '80',
      'experience': '1987391'
    },
    'mining': {
      'rank': '302428',
      'level': '82',
      'experience': '2569346'
    },
    'herblore': {
      'rank': '231272',
      'level': '94',
      'experience': '8428840'
    },
    'agility': {
      'rank': '311753',
      'level': '75',
      'experience': '1325351'
    },
    'thieving': {
      'rank': '351323',
      'level': '67',
      'experience': '563295'
    },
    'slayer': {
      'rank': '180192',
      'level': '99',
      'experience': '13051973'
    },
    'farming': {
      'rank': '212123',
      'level': '83',
      'experience': '2881720'
    },
    'runecrafting': {
      'rank': '353239',
      'level': '66',
      'experience': '533452'
    },
    'hunter': {
      'rank': '466118',
      'level': '56',
      'experience': '192617'
    },
    'construction': {
      'rank': '315849',
      'level': '75',
      'experience': '1269014'
    },
    'summoning': {
      'rank': '189379',
      'level': '97',
      'experience': '10826937'
    },
    'dungeoneering': {
      'rank': '224331',
      'level': '88',
      'experience': '4476217'
    },
    'divination': {
      'rank': '284247',
      'level': '80',
      'experience': '2021767'
    },
    'invention': {
      'rank': '175619',
      'level': '72',
      'experience': '9808846'
    },
    'archaeology': {
      'rank': '174083',
      'level': '47',
      'experience': '79837'
    }
  },
  'activities': {
    'bounty hunter': {
      'rank': '-1',
      'score': '-1'
    },
    'b.h. rogues': {
      'rank': '-1',
      'score': '-1'
    },
    'dominion tower': {
      'rank': '-1',
      'score': '-1'
    },
    'the crucible': {
      'rank': '-1',
      'score': '-1'
    },
    'castle wars games': {
      'rank': '-1',
      'score': '-1'
    },
    'b.a. attackers': {
      'rank': '-1',
      'score': '-1'
    },
    'b.a. defenders': {
      'rank': '-1',
      'score': '-1'
    },
    'b.a. collectors': {
      'rank': '-1',
      'score': '-1'
    },
    'b.a. healers': {
      'rank': '-1',
      'score': '-1'
    },
    'duel tournament': {
      'rank': '-1',
      'score': '-1'
    },
    'mobilising armies': {
      'rank': '-1',
      'score': '-1'
    },
    'conquest': {
      'rank': '-1',
      'score': '-1'
    },
    'fist of guthix': {
      'rank': '-1',
      'score': '-1'
    },
    'gg: athletics': {
      'rank': '-1',
      'score': '-1'
    },
    'gg: resource race': {
      'rank': '-1',
      'score': '-1'
    },
    'we2: armadyl lifetime contribution': {
      'rank': '-1',
      'score': '-1'
    },
    'we2: bandos lifetime contribution': {
      'rank': '-1',
      'score': '-1'
    },
    'we2: armadyl pvp kills': {
      'rank': '-1',
      'score': '-1'
    },
    'we2: bandos pvp kills': {
      'rank': '-1',
      'score': '-1'
    },
    'heist guard level': {
      'rank': '-1',
      'score': '-1'
    },
    'heist robber level': {
      'rank': '-1',
      'score': '-1'
    },
    'cfp: 5 game average': {
      'rank': '-1',
      'score': '-1'
    },
    'af15: cow tipping': {
      'rank': '-1',
      'score': '-1'
    },
    'af15: rats killed after the miniquest': {
      'rank': '-1',
      'score': '-1'
    },
    'runescore': {
      'rank': '277209',
      'score': '3255'
    },
    'clue scrolls easy': {
      'rank': '149033',
      'score': '2'
    },
    'clue scrolls medium': {
      'rank': '-1',
      'score': '-1'
    },
    'clue scrolls hard': {
      'rank': '-1',
      'score': '-1'
    },
    'clue scrolls elite': {
      'rank': '157308',
      'score': '5'
    },
    'clue scrolls master': {
      'rank': '-1',
      'score': '-1'
    }
  }
}
```

{% endtab %}
{% endtabs %}

### get\_current\_seasonal\_ranking(username: str)

> Gets a players current seasonal stats

| Parameters | Type  |
| ---------- | ----- |
| `username` | `str` |

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_current_seasonal_ranking("Maikeru") 
```

{% endtab %}

{% tab title="Response" %}

```python
[] # If there is no season in progress
# Or
[
  {
    'score_raw': 9504850,
    'endDate': '26 Oct 2017',
    'score_formatted': '9,504,850',
    'rank': 914,
    'hiscoreId': 1508152301821,
    'title': 'Dimension of the Damned Qualifier October 2017 Score',
    'startDate': '16 Oct 2017'
  }
]
```

{% endtab %}
{% endtabs %}

### get\_past\_seasonal\_ranking(username: str)

> Gets a players archived seasonal stats

| Parameter  | Type  |
| ---------- | ----- |
| `username` | `str` |

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_past_seasonal_ranking("Maikeru") 
```

{% endtab %}

{% tab title="Response" %}

```python
[
  {
    'score_raw': 9504850,
    'endDate': '26 Oct 2017',
    'score_formatted': '9,504,850',
    'rank': 914,
    'hiscoreId': 1508152301821,
    'title': 'Dimension of the Damned Qualifier October 2017 Score',
    'startDate': '16 Oct 2017'
  },
  {
    'score_raw': 62400,
    'endDate': '15 Oct 2017',
    'score_formatted': '00:01:02',
    'rank': 105,
    'hiscoreId': 1507507200004,
    'title': 'Fastest kill time: Queen Black Dragon',
    'startDate': '09 Oct 2017'
  },
  {
    'score_raw': 289800,
    'endDate': '08 Oct 2017',
    'score_formatted': '00:04:49',
    'rank': 1268,
    'hiscoreId': 1506902400021,
    'title': 'Fastest kill time: Nex (Solo)',
    'startDate': '02 Oct 2017'
  },
  {
    'score_raw': 58200,
    'endDate': '08 Oct 2017',
    'score_formatted': '00:00:58',
    'rank': 25,
    'hiscoreId': 1506902400017,
    'title': 'Fastest kill time: Queen Black Dragon',
    'startDate': '02 Oct 2017'
  }
]
```

{% endtab %}
{% endtabs %}

### get\_season\_details()

> Get details about the current ongoing season

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_season_details()
print(response)
```

{% endtab %}

{% tab title="Response" %}

```python
[] # If there is no current season
# Or
[
  {
    'status': 'ARCHIVED',
    'name': 'temp_hiscore_zombiescape_2017_october_finale_mk3',
    'id': 1510570900743,
    'recurrence': 0,
    'startDate': '18 Nov 2017',
    'endDate': '18 Nov 2017',
    'type': 'LONG',
    'title': 'Dimension of the Damned Finale October 2017 Score',
    'description': 'The players score during the finale.',
    'daysRunning': 1,
    'monthsRunning': 0
  }
]
```

{% endtab %}
{% endtabs %}

### get\_past\_season\_details()

> Get details about archived seasons

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_past_season_details()
print(response)
```

{% endtab %}

{% tab title="Response" %}

```python
[
  {
    'status': 'ARCHIVED',
    'name': 'temp_hiscore_zombiescape_2017_october_finale_mk3',
    'id': 1510570900743,
    'recurrence': 0,
    'startDate': '18 Nov 2017',
    'endDate': '18 Nov 2017',
    'type': 'LONG',
    'title': 'Dimension of the Damned Finale October 2017 Score',
    'description': 'The players score during the finale.',
    'daysRunning': 1,
    'monthsRunning': 0
  },
  {
    'status': 'ARCHIVED',
    'name': 'temp_hiscore_2017_araxxi_kill_time',
    'id': 1508716800048,
    'recurrence': 7,
    'startDate': '23 Oct 2017',
    'endDate': '29 Oct 2017',
    'type': 'TIME',
    'title': 'Fastest kill time: Araxxi (Solo)',
    'description': 'The fastest kill times for Araxxi (Solo).',
    'daysRunning': 7,
    'monthsRunning': 0
  },
  {
    'status': 'ARCHIVED',
    'name': 'temp_hiscore_2017_nex_kill_time',
    'id': 1508716800049,
    'recurrence': 7,
    'startDate': '23 Oct 2017',
    'endDate': '29 Oct 2017',
    'type': 'TIME',
    'title': 'Fastest kill time: Nex (Solo)',
    'description': 'The fastest kill times for Nex (Solo).',
    'daysRunning': 7,
    'monthsRunning': 0
  },
  # ... 100+ more items
]
```

{% endtab %}
{% endtabs %}

### get\_clan\_ranking()

> Get details about the top 3 clans

{% tabs %}
{% tab title="Python" %}

```python
response = hiscore.get_clan_ranking()
print(response)
```

{% endtab %}

{% tab title="Response" %}

```python
[
  {
    'rank': 1,
    'clan_name': 'Efficiency Experts',
    'clan_mates': 496,
    'xp_total': 805849140972
  },
  {
    'rank': 2,
    'clan_name': 'Maxed',
    'clan_mates': 469,
    'xp_total': 686603258905
  },
  {
    'rank': 3,
    'clan_name': 'Mining Golds',
    'clan_mates': 500,
    'xp_total': 435825433973
  }
]
```

{% endtab %}
{% endtabs %}
