# Athletics Rankings, Athletes & Calendar (`scrapermaster/athletics-rankings-athletes-calendar`) Actor

Athletics data: world rankings by event, athlete profiles with personal bests and honours, competition calendar, results and world records. Data from World Athletics.

- **URL**: https://apify.com/scrapermaster/athletics-rankings-athletes-calendar.md
- **Developed by:** [Scraper Master](https://apify.com/scrapermaster) (community)
- **Categories:** Sports, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.52 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Athletics Rankings, Athletes & Calendar

Collect public athletics data into clean, structured rows: weekly world rankings, athlete profiles, the competition calendar, competition results and records.

All data comes from World Athletics (worldathletics.org). This Actor is an independent tool and is not affiliated with or endorsed by World Athletics. Only publicly visible information is read; no login is used.

### Modes

Choose one with the `mode` input. Every mode respects `maxItems`. A problem with one input (for example an unknown athlete) produces a row with `"error": true` and the run continues.

#### rankings

Weekly world ranking lists for one event and sex, optionally limited to an area or a country, or taken from an earlier week.

```json
{ "mode": "rankings", "event": "marathon", "sex": "women", "regionType": "countries", "region": "ken", "maxItems": 50 }
```

`event` is the slug used in World Athletics ranking URLs (`100m`, `400m`, `marathon`, `high-jump`, `110mh`, `overall-ranking`). Place movement is computed by comparing with the previous weekly list (switch off with `includeMovement: false`). It is empty for athletes who were not in the part of the previous list that was read.

#### athlete

Full profile for athletes given by URL, numeric ID or name search.

```json
{ "mode": "athlete", "athletes": ["https://worldathletics.org/athletes/jamaica/oblique-seville-14737998", "14201847"], "searchNames": ["Faith Kipyegon"] }
```

#### calendar

Competitions for a year, with optional area, country, category, discipline and text filters.

```json
{ "mode": "calendar", "year": 2025, "area": "Europe", "category": "GW", "maxItems": 100 }
```

#### results

Result rows for one or more competitions, optionally narrowed to one event and sex. Competition IDs come from the calendar mode (`competitionId`). One request is needed per competition day.

```json
{ "mode": "results", "competitions": ["7132391"], "event": "100 Metres", "sex": "men", "maxItems": 200 }
```

#### records

World, U20, championship and Olympic record lists, chosen with `recordType`.

```json
{ "mode": "records", "recordType": "World Records", "event": "100 Metres" }
```

### Output fields

| Mode | Main fields |
| --- | --- |
| rankings | `rank`, `athlete`, `nationality`, `dateOfBirth`, `points`, `previousRank`, `placeMovement` (positive = moved up), `rankedEvents`, `event`, `sex`, `region`, `rankDate`, `athleteUrl` |
| athlete | `athleteId`, `name`, `country`, `countryCode`, `dateOfBirth`, `sex`, `disciplines`, `personalBests[]`, `seasonBestsSeason`, `seasonBests[]`, `honourSummary[]`, `honours[]` (medals and finals by category), `worldRankings[]` (current place per event), `bestWorldRankings[]`, `resultsByYear[]` (optional), `url` |
| calendar | `competitionId`, `name`, `startDate`, `endDate`, `dateRange`, `venue`, `countryCode`, `area`, `category`, `competitionGroup`, `disciplines`, `hasResults` |
| results | `competitionId`, `competition`, `venue`, `event`, `eventId`, `sex`, `round`, `date`, `place`, `athlete`, `country`, `mark`, `wind`, `points`, `qualified`, `records`, `remark`, `athleteUrl` |
| records | `recordType`, `sex`, `event`, `mark`, `wind`, `equalled`, `pending`, `athlete`, `country`, `dateOfBirth`, `venue`, `date`, `athleteUrl` |
| error row | `error`, `message`, `mode`, `input` |

### Notes and limitations

- Rankings and athlete profiles are read from the website's pages; the calendar, results, name search and records use the same public JSON endpoint that the website itself calls. That endpoint requires a public read-only key which is shipped inside the site's own JavaScript; it is kept as a named constant in `src/util.js`.
- The athlete profile shows one season of detailed results (the latest on the page). Older seasons are not fetched.
- Results are limited to what World Athletics publishes for a competition; older or small meetings may have no result rows. Decathlon and heptathlon discipline lines can appear under the matching single-event name.
- Area records are not included; use `recordType` values for world, championship and Olympic lists.
- Requests are made one at a time with random pauses of about one second and are retried with backoff on rate limiting or server errors. Large runs therefore take time.
- Page layouts and field names may change on the source website.

### Local test

```bash
npm install
./run-test.sh '{"mode":"rankings","event":"100m","sex":"men","maxItems":5}'
```

Rows are written to `storage/datasets/default`.

# Actor input Schema

## `mode` (type: `string`):

What to extract: world rankings, athlete profiles, the competition calendar, competition results, or records.

## `maxItems` (type: `integer`):

Maximum number of result rows to return.

## `event` (type: `string`):

Rankings: event slug as used in World Athletics URLs (100m, 400m, marathon, high-jump, 110mh, overall-ranking ...). Results and records: part of the event name, e.g. '100 Metres'.

## `sex` (type: `string`):

Men or women. Used by rankings (required), and as an optional filter for results and records.

## `regionType` (type: `string`):

Rankings only. World list, an area, or a single country.

## `region` (type: `string`):

Rankings only. For 'area': africa, asia, europe, north and central america, oceania, south america. For 'countries': a lowercase three-letter code such as usa, ken, jam.

## `rankDate` (type: `string`):

Rankings only. A weekly ranking date as YYYY-MM-DD (for example 2026-09-29). Leave empty for the latest list.

## `includeMovement` (type: `boolean`):

Rankings only. Also read the previous week's list to compute place movement. Costs a few extra page loads.

## `athletes` (type: `array`):

Athlete mode. Profile URLs (https://worldathletics.org/athletes/jamaica/oblique-seville-14737998) or numeric athlete IDs (14737998).

## `searchNames` (type: `array`):

Athlete mode. Names to look up; the best matches are fetched as full profiles.

## `searchResultsPerName` (type: `integer`):

Athlete mode. How many search matches to fetch per name.

## `includeResultsByYear` (type: `boolean`):

Athlete mode. Adds the athlete's results list for the season shown on the profile page.

## `year` (type: `integer`):

Calendar mode. Year of the competitions.

## `area` (type: `string`):

Calendar mode, optional. Africa, Asia, Europe, North and Central America, Oceania or South America.

## `country` (type: `string`):

Calendar mode, optional. Country name (Kenya) or three-letter code (KEN).

## `category` (type: `string`):

Calendar mode, optional. Ranking category code, for example OW, DF, GW, A, B, C, D, E, F.

## `discipline` (type: `string`):

Calendar mode, optional. For example Road Running, Track and Field, Race Walking, Combined Events.

## `query` (type: `string`):

Calendar mode, optional. Free-text filter on competition name.

## `competitions` (type: `array`):

Results mode. Competition IDs or URLs containing eventId=ID (IDs appear in the calendar mode output).

## `recordType` (type: `string`):

Records mode. For example 'World Records', 'World U20 Records', 'Olympic Games Records', 'World Championships in Athletics Records', 'World Best Performances'.

## Actor input object example

```json
{
  "mode": "rankings",
  "maxItems": 25,
  "event": "100m",
  "sex": "men",
  "regionType": "world",
  "includeMovement": true,
  "searchResultsPerName": 1,
  "includeResultsByYear": true,
  "year": 2025,
  "competitions": [
    "7132391"
  ],
  "recordType": "World Records"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "maxItems": 25,
    "event": "100m",
    "year": 2025,
    "competitions": [
        "7132391"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapermaster/athletics-rankings-athletes-calendar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "maxItems": 25,
    "event": "100m",
    "year": 2025,
    "competitions": ["7132391"],
}

# Run the Actor and wait for it to finish
run = client.actor("scrapermaster/athletics-rankings-athletes-calendar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "maxItems": 25,
  "event": "100m",
  "year": 2025,
  "competitions": [
    "7132391"
  ]
}' |
apify call scrapermaster/athletics-rankings-athletes-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,scrapermaster/athletics-rankings-athletes-calendar"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/JjfcEawdo9Cf5SRf3/builds/EQbBVqZlJSgngb3x7/openapi.json