Docs menu
SofaScore API endpoint
SofaScore search by entity type API
Searches SofaScore for one entity type and returns up to 20 ranked results per page: `events` (matches), `teams`, `players` (with team and position), `managers`, `referees`, `venues` (with city and capacity) and `unique_tournaments` (competitions with category). Page with the zero-based `page`; an empty page means there are no further results. The optional `sport` filter (any key listed by sofascore/sports, such as `football`, `basketball`, `tennis` or `mma`) narrows `teams`, `players`, `managers` and `unique_tournaments`, and is rejected for `events`, `referees` and `venues`, which ignore it. Use the returned ids with the matching endpoints (team, player, manager, venue, tournament-seasons, event).
GETapiKey1 credit/requestSofaScoresofascore.searchTypedResponseDoc
SofaScore/sofascore/search-typedEndpoint facts
- Method
- GET
- API path
- /sofascore/search-typed
- Auth
- apiKey
- Credits
- 1 credit/request
- Charged on
- Successful 2xx responses only
- Platform
- SofaScore
- Response schema
- #/definitions/sofascore.searchTypedResponseDoc
How this endpoint behaves
Searches SofaScore for one entity type and returns up to 20 ranked results per page for that type. Use it instead of sofascore/search when you need one kind of entity, deeper pages, or a sport filter.
Query parameters:
type: required enum. Allowed values:events(matches),teams,players,managers,referees,venues,unique_tournaments(competitions).q: required. Free-text query, up to 128 characters.page: optional integer, 0 or more. Zero-based page number. Defaults to0. Pages hold up to 20 results.sport: optional enum, valid only forteams,players,managersandunique_tournaments. Allowed values:american-football,aussie-rules,badminton,bandy,baseball,basketball,beach-volley,cricket,darts,esports,floorball,football,futsal,handball,ice-hockey,mma,minifootball,padel,rugby,snooker,table-tennis,tennis,volleyball,waterpolo. The same keys are listed bysofascore/sports.
Notable response behavior:
- Every result has
type(event,team,player,manager,referee,venueorunique_tournament),id,name,slugandscore, SofaScore's relevance score (results are ordered by it). Other fields are set only for the types that have them:- team:
short_name,name_code,sport,country,gender,national,user_count. - player:
short_name,position,jersey_number,team,country,retired,deceased. - manager:
sport,country,deceased. referee:sport,country. - venue:
city,country,capacity. - unique_tournament:
category_id,category_name,sport,gender. - event:
event, the same match summary the event lists use (teams, status, score, tournament, start time), andsport.
- team:
- There is no total or next-page flag: a full page holds up to 20 results, and an empty
resultslist means there are no matches or the page is past the last one (a page far past the end returns an empty list, not an error). A query that matches nothing is a normal 200. typeis validated here. SofaScore does not reject an unknown search path (it answered 200 with unrelated players), so an unsupportedtypereturns 400.sportis validated for the same reason, because SofaScore ignores an unknown sport and returns unfiltered results.sportfiltersteams,players,managersandunique_tournamentsupstream (for examplesport=futsalreturns only futsal clubs). SofaScore ignores it forevents,refereesandvenues, so passing it for those types returns 400 rather than looking like a filter.- A negative
pageand an emptyqare rejected with 400 before any upstream request.
Example response (shortened):
{
"code": 200,
"msg": "OK",
"data": {
"type": "players",
"query": "haaland",
"sport": "football",
"page": 0,
"count": 10,
"source_url": "https://api.sofascore.com/api/v1/search/players?q=haaland&sport=football",
"fetched_at": "2026-10-07T14:00:00Z",
"results": [
{
"type": "player",
"id": 839956,
"name": "Erling Haaland",
"slug": "erling-haaland",
"score": 127450.195,
"short_name": "E. Haaland",
"country": "Norway",
"user_count": 1118701,
"position": "F",
"jersey_number": "9",
"team": { "id": 17, "name": "Manchester City", "slug": "manchester-city" }
}
]
}
}
Live monitoring
- Monitored request
- GET /sofascore/search-typed?q=arsenal&type=teams
- Checks passed, 7 days to 14 Oct 2026
- 100%
- Median response time
- 0.86 s
Sampled response
- Request, 14 Oct 2026
- GET /sofascore/search-typed?q=arsenal&type=teams
- Items in results
- 20
- Fields filled in every checked item
- 8
- Fields empty in some or all items
- 2
| Field | Filled in, of 20 checked | Values in the sample |
|---|---|---|
| type | 20 | team in all 20 |
| id | 20 | |
| name | 20 | “Arsenal” and 17 other values |
| slug | 20 | |
| score | 20 | 2,128.44 to 268,375, median 4,515.09 |
| name_code | 20 | |
| sport | 20 | football (19), handball (1) |
| country | 18 | England (8), Russia (3), Argentina (2) and 5 more |
| gender | 19 | |
| user_count | 20 | 233 to 3,720,306, median 1,052 |
Request parameters
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| type | string | Yes | Entity type to search Allowed values: events, teams, players, managers, referees, venues, unique_tournaments. | teams | |
| q | string | Yes | Search text, up to 128 characters | arsenal | |
| page | integer | No | 0 | Zero-based page number. Defaults to 0 Minimum: 0. | 0 |
| sport | string | No | Restrict teams, players, managers or unique_tournaments to one sport Allowed values: american-football, aussie-rules, badminton, bandy, baseball, basketball, beach-volley, cricket, darts, esports, floorball, football, futsal, handball, ice-hockey, mma, minifootball, padel, rugby, snooker, table-tennis, tennis, volleyball, waterpolo. | football | |
| x-api-key (header) | string | Yes | API key required |
cURL example
curl -X GET "https://api.crawlora.net/api/v1/sofascore/search-typed?type=teams&q=arsenal&page=1&sport=american-football" \ -H "x-api-key: $CRAWLORA_API_KEY"
Example JSON response
{
"code": 200,
"msg": "OK",
"data": {
"type": "players",
"query": "haaland",
"sport": "football",
"page": 0,
"count": 10,
"source_url": "https://api.sofascore.com/api/v1/search/players?q=haaland&sport=football",
"fetched_at": "2026-10-07T14:00:00Z",
"results": [
{
"type": "player",
"id": 839956,
"name": "Erling Haaland",
"slug": "erling-haaland",
"score": 127450.195,
"short_name": "E. Haaland",
"country": "Norway",
"user_count": 1118701,
"position": "F",
"jersey_number": "9",
"team": {
"id": 17,
"name": "Manchester City",
"slug": "manchester-city"
}
}
]
}
}Request schema
No body schema
Response schema
#/definitions/sofascore.searchTypedResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | sofascore.SearchTypedResponse | No | ||||
| data.count | integer | No | ||||
| data.fetched_at | string | No | ||||
| data.page | integer | No | ||||
| data.query | string | No | ||||
| data.results | array | No | ||||
| data.results[].capacity | integer | No | 60704 | |||
| data.results[].category_id | integer | No | 1 | Competition fields. | ||
| data.results[].category_name | string | No | England | |||
| data.results[].city | string | No | London | Venue fields. | ||
| data.results[].country | string | No | England | |||
| data.results[].deceased | boolean | No | Deceased applies to players and managers. | |||
| data.results[].event | object | No | Event is the match summary of an event result. | |||
| data.results[].event.away_score | object | No | Away side's score, when available. | |||
| data.results[].event.away_score.current | integer | No | Current score, which is the final score once the match is over. | |||
| data.results[].event.away_score.period1 | integer | No | Score in the first period. | |||
| data.results[].event.away_score.period2 | integer | No | Score in the second period. | |||
| data.results[].event.away_team | object | No | Away side. | |||
| data.results[].event.away_team.country | string | No | Spain | Country the team belongs to. | ||
| data.results[].event.away_team.id | integer | No | 2817 | SofaScore team id. Use it with the team endpoints. | ||
| data.results[].event.away_team.name | string | No | FC Barcelona | Full team name. | ||
| data.results[].event.away_team.national | boolean | No | True for a national team. | |||
| data.results[].event.away_team.short_name | string | No | Barcelona | Shortened team name. | ||
| data.results[].event.away_team.slug | string | No | barcelona | URL slug of the team on SofaScore. | ||
| data.results[].event.home_score | object | No | Home side's score, when available. | |||
| data.results[].event.home_score.current | integer | No | Current score, which is the final score once the match is over. | |||
| data.results[].event.home_score.period1 | integer | No | Score in the first period. | |||
| data.results[].event.home_score.period2 | integer | No | Score in the second period. | |||
| data.results[].event.home_team | object | No | Home side. | |||
| data.results[].event.home_team.country | string | No | Spain | Country the team belongs to. | ||
| data.results[].event.home_team.id | integer | No | 2817 | SofaScore team id. Use it with the team endpoints. | ||
| data.results[].event.home_team.name | string | No | FC Barcelona | Full team name. | ||
| data.results[].event.home_team.national | boolean | No | True for a national team. | |||
| data.results[].event.home_team.short_name | string | No | Barcelona | Shortened team name. | ||
| data.results[].event.home_team.slug | string | No | barcelona | URL slug of the team on SofaScore. | ||
| data.results[].event.id | integer | No | 14025013 | SofaScore event id. Use it with the event endpoints. | ||
| data.results[].event.slug | string | No | URL slug of the match on SofaScore. | |||
| data.results[].event.start_time | string | No | 2025-08-15T19:00:00Z | Start time in UTC (RFC 3339). | ||
| data.results[].event.start_timestamp | integer | No | Start time as a Unix timestamp in seconds. | |||
| data.results[].event.status | object | No | Current status of the match. | |||
| data.results[].event.status.code | integer | No | SofaScore's numeric status code, for example 0 for not started and 100 for ended. | |||
| data.results[].event.status.description | string | No | Ended | Status as displayed, for example "Ended". | ||
| data.results[].event.status.type | string | No | finished | Status group, for example `notstarted`, `inprogress` or `finished`. | ||
| data.results[].event.tournament | object | No | Tournament and parent competition the match belongs to. | |||
| data.results[].event.tournament.category | string | No | England | Category the tournament sits under, usually a country or region. | ||
| data.results[].event.tournament.id | integer | No | SofaScore id of the tournament the match is filed under. The seasons, standings and round endpoints take `unique_tournament_id` instead. | |||
| data.results[].event.tournament.name | string | No | Premier League | Tournament name. | ||
| data.results[].event.tournament.slug | string | No | premier-league | URL slug of the tournament on SofaScore. | ||
| data.results[].event.tournament.unique_tournament_id | integer | No | 17 | Id of the parent competition. This is the tournament id the tournament-seasons, standings and round-events endpoints take. | ||
| data.results[].event.tournament.unique_tournament_name | string | No | Premier League | Name of the parent competition. | ||
| data.results[].event.winner_code | integer | No | Result code: 1 when the home side won, 2 when the away side won, 3 for a draw. Omitted until the match is decided. | |||
| data.results[].gender | string | No | M | |||
| data.results[].id | integer | No | 42 | |||
| data.results[].jersey_number | string | No | ||||
| data.results[].name | string | No | Arsenal | |||
| data.results[].name_code | string | No | ||||
| data.results[].national | boolean | No | ||||
| data.results[].position | string | No | F | Player fields. | ||
| data.results[].retired | boolean | No | ||||
| data.results[].score | number | No | 272039.88 | Score is SofaScore's relevance score; results are ordered by it. | ||
| data.results[].short_name | string | No | ||||
| data.results[].slug | string | No | arsenal | |||
| data.results[].sport | string | No | football | |||
| data.results[].team | sofascore.TeamRef | No | TeamRef record, 6 fields: country, id, name, national, short_name, slug. Described under SofaScore venue API. | |||
| data.results[].type | string | No | team | Type is event, team, player, manager, referee, venue or unique_tournament. | ||
| data.results[].user_count | integer | No | ||||
| data.source_url | string | No | ||||
| data.sport | string | No | ||||
| data.type | string | No | teams | |||
| msg | string | No | OK |
Failure responses
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Code examples
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/sofascore/search-typed?type=teams&q=arsenal&page=1&sport=american-football" \
-H "x-api-key: $CRAWLORA_API_KEY"Shared guides
Related
More SofaScore endpoint docsSofaScore APISofaScore categories for a sport API documentationSofaScore competitions in a category API documentationSofaScore league draft picks API documentationSofaScore league draft API documentationSofaScore esports game detail API documentationSofaScore event at-bat pitches API documentation