# Topscorer standings

## Step 1: Gather the tools 

You are going to need the following tools:

* Sportmonks' API token
* Code editor (Visual studio used in examples)
* Postman (optional)

You can find a link to another article where we discuss the tools in-depth on our [**Developer Tools Guide.**](/v2/how-to-guides/developer-tools.md)

## Step 2: Determine the league and season

What league and specifically what season interests you? For this guide, we’ll go with the 20/21 season of the **Scottish Premiership** **(league id: 501, season id: 17141).**

## Step 3: Choose the correct endpoint

Requesting top scorers can be done with the endpoint: [**get topscorers by season id.**](https://football-postman.sportmonks.com/#0c5c54ec-c2da-410a-9965-78c060f6b7a4)

```javascript
https://soccer.sportmonks.com/api/v2.0/topscorers/season/17141?api_token={API_TOKEN}
```

However, we will slightly modify the request because we want the player and team names and not just their player id. We can do this for all three top scorers, which are:

* Goalscorers → players who have scored a goal
* Assistscorers → players who gave assists
* Cardscorers → players who have received yellow or red cards

We then plug the nested includes`goalscorers.player`and`goalscorers.team`to the request. So we could for example request everything:

```javascript
https://soccer.sportmonks.com/api/v2.0/topscorers/season/17141?api_token={API_TOKEN}&include=goalscorers.player,goalscorers.team,assistscorers.player,assistscorers.team,cardscorers.player,cardscorers.team
```

It’s up to you how much data you want to receive. For our example, we are only interested in the goal-scoring top scorers. So we’ll use this URL:

```javascript
https://soccer.sportmonks.com/api/v2.0/topscorers/season/17141?api_token={API_TOKEN}&include=goalscorers.player,goalscorers.team
```

## Step 4: Analyze the response

```javascript
"position": 1,
                    "season_id": 17141,
                    "player_id": 173059,
                    "team_id": 66,
                    "stage_id": 77447501,
                    "goals": 6,
                    "penalty_goals": 1,
                    "type": "goals",
                    "player": {
                        "data": {
                            "player_id": 173059,
                            "team_id": 66,
                            "country_id": 1161,
                            "position_id": 4,
                            "common_name": "K. Nisbet",
                            "display_name": "Kevin Nisbet",
                            "fullname": "Kevin Nisbet",
                            "firstname": "Kevin",
                            "lastname": "Nisbet",
                            "nationality": "Scotland",
                            "birthdate": "08/03/1997",
                            "birthcountry": "Scotland",
                            "birthplace": "Glasgow",
                            "height": "180 cm",
                            "weight": null,
                            "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png"
                        }
},
                    "team": {
                        "data": {
                            "id": 66,
                            "legacy_id": 702,
                            "name": "Hibernian",
                            "short_code": "HIB",
                            "twitter": "@HibernianFC",
                            "country_id": 1161,
                            "national_team": false,
                            "founded": 1875,
                            "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/2/66.png",
                            "venue_id": 8946,
                            "current_season_id": 17141
```

We can see that the Scottish Premiership’s top scorer is Kevin Nisbet from Hibernian with six goals including one penalty goal.

For more detailed information you can head to our [**leagues & topscorers tutorial**](/v2/tutorials/league-and-topscorers-standings.md)**.**

{% content-ref url="/pages/-MM\_Cwjnz-a2R2kD-1-e" %}
[League & topscorers standings](/v2/tutorials/league-and-topscorers-standings.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportmonks.com/v2/how-to-guides/how-to-build-standings-and-topscorer-standings/topscorer-standings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.