ShanghaiRanking APIshanghairanking.com ↗
Access ARWU world university rankings, GRAS subject rankings, and university profiles via the ShanghaiRanking API. Filter by year, region, and subject.
What is the ShanghaiRanking API?
The ShanghaiRanking API provides structured access to university rankings data across 5 endpoints, covering ARWU world rankings, GRAS subject-level rankings, Chinese university lists, and individual university profiles. The get_arwu_rankings endpoint returns ranked universities with scores, national ranks, and region codes for a given year, with optional filtering by region name.
curl -X GET 'https://api.parse.bot/scraper/9a025ecd-9ccb-4cf6-a454-be52e290b946/get_chinese_universities?limit=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace shanghairanking-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Shanghai Ranking API — world rankings, subject rankings, and university search."""
from parse_apis.Shanghai_Ranking_API import (
ShanghaiRanking, Year, SubjectCode, NotFoundError
)
client = ShanghaiRanking()
# Search for universities by name, inspect the top result.
result = client.university_summaries.search(query="MIT", limit=1).first()
if result:
print(result.name, result.ranking, result.region, result.ranking_info)
# ARWU world rankings for 2024, bounded iteration.
for entry in client.ranked_universities.arwu(year=Year._2024, limit=5):
print(entry.rank, entry.name, entry.score, entry.region)
# GRAS subject rankings — Computer Science & Engineering.
for entry in client.ranked_universities.gras(subject_code=SubjectCode.AS0210, year=Year._2024, limit=3):
print(entry.rank, entry.name, entry.score, entry.region_code)
# List Chinese universities with their world ranking positions.
for cu in client.chinese_universities.list(limit=5):
print(cu.name, cu.world_ranking, cu.slug)
# Typed error handling around a search call.
try:
results = client.university_summaries.search(query="NonExistentXYZ123", limit=1).first()
if results:
print(results.name)
else:
print("No results found for query")
except NotFoundError as exc:
print(f"Not found: {exc}")
print("exercised: university_summaries.search / ranked_universities.arwu / ranked_universities.gras / chinese_universities.list")
Retrieve a list of Chinese universities with their current ARWU world ranking position. Each entry includes university name, slug identifier, world ranking, and region. The list is ordered by world ranking. Use the slug to fetch full university details via get_university_detail.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of universities to return. |
{
"type": "object",
"fields": {
"total": "integer total count of universities returned",
"universities": "array of university objects with name, slug, world_ranking, cs_ranking, website, region"
},
"sample": {
"data": {
"total": 1,
"universities": [
{
"name": "Tsinghua University",
"slug": "tsinghua-university",
"region": "China",
"website": "N/A",
"cs_ranking": "N/A",
"world_ranking": "18"
}
]
},
"status": "success"
}
}About the ShanghaiRanking API
ARWU and GRAS Rankings
The get_arwu_rankings endpoint accepts a year parameter (e.g. '2024') and an optional region filter using full region names such as 'United States' or 'China Mainland'. Each result in the rankings array includes rank, name, slug, region, region_code, national_rank, and score. The get_gras_subject_rankings endpoint works similarly but also requires a subject_code — for example, 'AS0210' for Computer Science & Engineering or 'AS0101' for Mathematics — and returns the same ranking shape with the subject code echoed back in the response.
University Search and Chinese University List
The search_universities endpoint accepts a query string for substring name matching and an optional region filter. Results include nameEn, univLogo, univUp (the slug used in other endpoints), region, rankingInfo, and ranking. The get_chinese_universities endpoint returns a flat list of Chinese universities with world_ranking, cs_ranking, website, and region, and accepts a limit parameter to cap result size.
University Detail Profiles
The get_university_detail endpoint takes a slug (obtainable from search_universities or get_chinese_universities) and returns a profile including name, address, website, found_year, and a subject_rankings array listing each subject and the university's rank in it. Slugs follow a human-readable format such as 'harvard-university' or 'tsinghua-university'.
The ShanghaiRanking API is a managed, monitored endpoint for shanghairanking.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when shanghairanking.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official shanghairanking.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a university comparison tool using ARWU scores and national ranks from
get_arwu_rankings. - Track year-over-year ranking changes for a specific institution by querying multiple years.
- Filter top-ranked universities by region to generate country-specific leaderboards.
- Retrieve subject-specific standings for Computer Science or Mathematics programs via
get_gras_subject_rankings. - Populate institution profiles with founding year, address, and website from
get_university_detail. - Search universities by partial name and region for autocomplete or lookup features using
search_universities. - List Chinese universities with their world and CS rankings for a regional higher-education dashboard.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does ShanghaiRanking have an official developer API?+
What does the `get_gras_subject_rankings` endpoint return, and which subject codes are supported?+
rank, name, slug, region, national_rank, and score. The documented subject codes are 'AS0210' for Computer Science & Engineering and 'AS0101' for Mathematics. Other subject codes may work but are not explicitly listed in the current spec.Does the API cover historical rankings beyond 2024?+
year parameter on get_arwu_rankings and get_gras_subject_rankings accepts arbitrary year strings, but coverage of earlier years depends on what ShanghaiRanking publishes. Results for years with no data may be empty. You can fork this API on Parse and revise it to add explicit year-range validation or a dedicated historical-years endpoint.Does the API return citation counts, h-index, or raw indicator scores used to compute ARWU rankings?+
score, rank, and national_rank fields, but not the underlying sub-indicators (such as alumni Nobel laureates, highly cited researchers, or Nature/Science papers) that feed into the ARWU methodology. You can fork it on Parse and revise to add the missing endpoint if those fields become accessible.Can I paginate through ARWU results, or is the full ranked list returned at once?+
get_arwu_rankings endpoint does not expose pagination parameters — it returns all matching universities in a single response. The get_chinese_universities endpoint accepts a limit integer to cap the result count, but there is no offset or cursor parameter across any endpoint.