# Sherdog MMA profile scraper (`richard.biros/sherdog-profile-scraper`)

This scraper extracts detailed information from Sherdog MMA fighter profiles.

- **URL**: https://beta-securitybyobscurity.apify.com/richard.biros/sherdog-profile-scraper.md
- **Developed by:** [Richard Biroš](https://beta-securitybyobscurity.apify.com/richard.biros) (community)
- **Categories:** Other
- **Stats:** 9 total users, 5 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 results

This Actor is paid per result. You are not charged for the Apify platform usage, but only a fixed price for dataset items the Actor outputs.

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

# README

## Sherdog API - Fighter Search & Scraper

A powerful web scraper built with [Crawlee](https://crawlee.dev/) and [Cheerio](https://cheerio.js.org/) that searches for and extracts comprehensive fighter profile data from [Sherdog](https://www.sherdog.com/), the world's largest MMA database.

### 🥊 Features

This scraper searches for fighters based on various criteria and extracts detailed information from their Sherdog profiles.

#### Search Capabilities

- **Search by Name** - Find fighters by partial name matches
- **Filter by Weight Class** - Search within specific weight divisions
- **Filter by Association** - Find fighters from specific gyms/teams
- **Pagination Support** - Automatically searches multiple pages for results
- **Results Limiting** - Control the number of fighters to scrape

#### Extracted Data

- **Basic Information** - Name, nickname, country, association, weight class
- **Fight Record** - Overall record, wins/losses breakdown by method
- **Physical Measurements** - Height and weight in metric or imperial units
- **Personal Information** - Age, birth date, profile image URL
- **Fight History** - Complete fight-by-fight breakdown with opponent, event, method, referee, round, and time details
- **Upcoming fight** - If there is a upcoming fight the details about it will be provided

### 📋 Input Configuration

The scraper accepts the following input parameters:

```json
{
  "searchTerm": "McGregor",
  "weightClass": "6",
  "association": "SBG Ireland",
  "resultsLimit": 50,
  "units": "metric"
}
```

#### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `searchTerm` | String | Yes\* | - | Fighter name to search for |
| `weightClass` | String | Yes\* | - | Weight class filter (see table below) |
| `association` | String | Yes\* | - | Gym/team name to filter by |
| `resultsLimit` | Number | No | 10 | Maximum number of fighters to scrape |
| `units` | String | No | `"metric"` | Measurement units: `"metric"` or `"imperial"` |

\*At least one of `searchTerm`, `weightClass`, or `association` must be provided.

#### Weight Class Codes

| Weight Class | Code |
|--------------|------|
| Super Heavyweight | `"1"` |
| Heavyweight | `"2"` |
| Light Heavyweight | `"3"` |
| Middleweight | `"4"` |
| Welterweight | `"5"` |
| Lightweight | `"6"` |
| Featherweight | `"7"` |
| Bantamweight | `"9"` |
| Flyweight | `"10"` |
| Catchweight | `"11"` |
| Strawweight | `"13"` |
| Atomweight | `"15"` |
| Minimumweight | `"17"` |

### 📊 Output Format

Each scraped fighter profile returns a structured JSON object:

```json
{
  "profileUrl": "https://www.sherdog.com/fighter/Conor-McGregor-29688",
  "name": "Conor McGregor",
  "nickname": "The Notorious",
  "country": "Ireland",
  "record": "22-6-0",
  "wins": 22,
  "koWins": 19,
  "subWins": 1,
  "decWins": 2,
  "losses": 6,
  "koLosses": 1,
  "subLosses": 4,
  "decLosses": 1,
  "draws": 0,
  "age": 35,
  "birthDate": "1988-07-14",
  "height": "175 cm",
  "weight": "70 kg",
  "association": "SBG Ireland",
  "weightClass": "Lightweight",
  "fighterImageUrl": "https://sherdog.com/image_crop/200/300/_images/fighter/20140714000000/Conor_McGregor.JPG",
  "fightHistory": [
    {
      "result": "win",
      "opponentName": "Donald Cerrone",
      "opponentSherdogUrl": "https://www.sherdog.com/fighter/Donald-Cerrone-12345",
      "eventName": "UFC 246 - McGregor vs. Cerrone",
      "eventSherdogUrl": "https://www.sherdog.com/events/UFC-246-McGregor-vs-Cerrone-78901",
      "eventDate": "Jan / 18 / 2020",
      "method": "TKO (Head Kick and Punches)",
      "refereeName": "Herb Dean",
      "refereeSherdogUrl": "https://www.sherdog.com/referee/Herb-Dean-5",
      "round": 1,
      "time": "0:40"
    },
    {
      "result": "loss",
      "opponentName": "Khabib Nurmagomedov",
      "opponentSherdogUrl": "https://www.sherdog.com/fighter/Khabib-Nurmagomedov-23456",
      "eventName": "UFC 229 - Khabib vs. McGregor",
      "eventSherdogUrl": "https://www.sherdog.com/events/UFC-229-Khabib-vs-McGregor-67890",
      "eventDate": "Oct / 06 / 2018",
      "method": "Submission (Rear-Naked Choke)",
      "refereeName": "Herb Dean",
      "refereeSherdogUrl": "https://www.sherdog.com/referee/Herb-Dean-5",
      "round": 4,
      "time": "3:03"
    }
  ]
}
```

### 🌐 How It Works

1. **Search Phase**: The scraper starts by searching Sherdog's fighter database using your criteria
2. **Discovery**: It finds fighter profile URLs from search results across multiple pages
3. **Scraping**: For each discovered fighter, it extracts detailed profile information including complete fight history
4. **Output**: All fighter data is saved to the dataset in structured JSON format

### 📊 Fight History Data

The scraper now extracts comprehensive fight-by-fight history for each fighter, including:

#### Fight History Fields

- **Result** - Win, loss, draw, or no contest
- **Opponent** - Name and Sherdog profile URL
- **Event** - Event name, URL, and date
- **Method** - How the fight ended (TKO, Submission, Decision, etc.)
- **Referee** - Referee name and profile URL (when available)
- **Round** - Which round the fight ended
- **Time** - Time within the round when the fight ended

#### Example Fight History Entry

```json
{
  "result": "win",
  "opponentName": "Donald Cerrone",
  "opponentSherdogUrl": "https://www.sherdog.com/fighter/Donald-Cerrone-12345",
  "eventName": "UFC 246 - McGregor vs. Cerrone",
  "eventSherdogUrl": "https://www.sherdog.com/events/UFC-246-McGregor-vs-Cerrone-78901",
  "eventDate": "Jan / 18 / 2020",
  "method": "TKO (Head Kick and Punches)",
  "refereeName": "Herb Dean",
  "refereeSherdogUrl": "https://www.sherdog.com/referee/Herb-Dean-5",
  "round": 1,
  "time": "0:40"
}
```

### 📈 Usage Examples

#### Search MMA fighters by Name

```json
{
  "searchTerm": "McGregor",
  "resultsLimit": 10,
  "units": "metric"
}
```

#### Search MMA fighters by Weight Class

```json
{
  "weightClass": "6",
  "resultsLimit": 100,
  "units": "imperial"
}
```

#### Search MMA fighters by Association/Gym

```json
{
  "association": "SBG Ireland",
  "resultsLimit": 50,
  "units": "metric"
}
```

#### Combined Search

```json
{
  "searchTerm": "Silva",
  "weightClass": "4",
  "association": "Chute Boxe",
  "resultsLimit": 25,
  "units": "metric"
}
```

### ⚙️ Configuration Options

#### Units Configuration

- **Metric**: Heights in cm, weights in kg
- **Imperial**: Heights in ft/in, weights in lbs

#### Results Limiting

- Set `resultsLimit` to control how many fighters to scrape
- Useful for testing or when you only need a subset of results
- Leave undefined to scrape all available fighters

### 🔍 Search Behavior

- **Partial Matching**: Search terms work with partial name matches
- **Case Insensitive**: Searches are not case-sensitive
- **Pagination**: Automatically searches multiple pages until results limit is reached
- **Deduplication**: Each fighter profile is only scraped once

### 📦 Output Dataset

The scraper saves all fighter data to the default dataset. Each item contains:

- Complete fighter profile information
- Original search criteria used
- Timestamp of when the data was scraped

### 🚀 Performance

- **Concurrent Scraping**: Multiple fighter profiles are scraped simultaneously
- **Proxy Support**: Built-in proxy rotation for reliable scraping
- **Error Handling**: Graceful handling of network errors and missing data
- **Rate Limiting**: Respectful scraping with built-in delays

# Actor input Schema

## `searchTerm` (type: `string`):

Search term to find fighters, nicknames, events, referees.

## `weightClass` (type: `string`):

Weight class to find fighters.

## `association` (type: `string`):

Association/Gym the fighter is associated with.

## `units` (type: `string`):

Select either metric or imperial units for weight.

## `resultsLimit` (type: `integer`):

Maximum number of results to return.

## Actor input object example

```json
{
  "units": "metric",
  "resultsLimit": 10
}
```

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("richard.biros/sherdog-profile-scraper").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("richard.biros/sherdog-profile-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call richard.biros/sherdog-profile-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=richard.biros/sherdog-profile-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Sherdog MMA profile scraper",
        "description": "This scraper extracts detailed information from Sherdog MMA fighter profiles.",
        "version": "0.0",
        "x-build-id": "ApIt4NFasPSVvEhk6"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/richard.biros~sherdog-profile-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-richard.biros-sherdog-profile-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/richard.biros~sherdog-profile-scraper/runs": {
            "post": {
                "operationId": "runs-sync-richard.biros-sherdog-profile-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/richard.biros~sherdog-profile-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-richard.biros-sherdog-profile-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "searchTerm": {
                        "title": "Search fighters, nicknames, events, referees",
                        "type": "string",
                        "description": "Search term to find fighters, nicknames, events, referees."
                    },
                    "weightClass": {
                        "title": "Weight Class",
                        "enum": [
                            "11",
                            "17",
                            "15",
                            "13",
                            "10",
                            "9",
                            "7",
                            "6",
                            "5",
                            "4",
                            "3",
                            "2",
                            "1"
                        ],
                        "type": "string",
                        "description": "Weight class to find fighters."
                    },
                    "association": {
                        "title": "Association",
                        "type": "string",
                        "description": "Association/Gym the fighter is associated with."
                    },
                    "units": {
                        "title": "Units",
                        "enum": [
                            "metric",
                            "imperial"
                        ],
                        "type": "string",
                        "description": "Select either metric or imperial units for weight.",
                        "default": "metric"
                    },
                    "resultsLimit": {
                        "title": "Results Limit",
                        "type": "integer",
                        "description": "Maximum number of results to return.",
                        "default": 10
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
