topuniversities APItopuniversities.com ↗
Access QS World University Rankings data: world and subject rankings, per-indicator scores, university profiles, and location filter vocabularies across multiple edition years.
What is the topuniversities API?
This API exposes QS World University Rankings data across 5 endpoints, covering overall world rankings by edition year, subject-specific rankings, and full university profile pages. Use get_world_rankings to retrieve paginated ranking tables with per-indicator scores and tied/banded rank strings, or get_subject_rankings to pull discipline-specific tables — both filterable by region, country, city, and text search. get_university_profile returns structured address, student/faculty headcounts, and the university's current positions across all QS rankings shown on its profile.
curl -X GET 'https://api.parse.bot/scraper/9edae581-c058-4a50-bf4c-ba847862c367/get_world_rankings?items_per_page=10' \ -H 'X-API-Key: $PARSE_API_KEY'
Returns one page of the QS World University Rankings table for an edition year (latest edition when year is omitted). Each row carries the displayed rank (may be tied, e.g. '=2', or banded, e.g. '801+'), a numeric rank_sort when the rank is a plain integer, overall score, country/region/city, the profile slug, and every indicator score/rank grouped by lens (Research & Discovery, Employability, etc.). Filters (region, country_code, city, search) and sorting are applied by the site. Pagination is 0-based via page and items_per_page (max 100); total_universities, total_pages and has_more come from the site. Two round trips per call.
| Param | Type | Description |
|---|---|---|
| city | string | City name from list_locations.regions[*].countries[*].cities. Omitted = all cities. |
| page | string | 0-based page index. |
| year | string | 4-digit edition year, e.g. 2026. Omitted = latest edition; available editions are listed by list_locations.edition_years. |
| region | string | Region name exactly as returned by list_locations.regions[*].region (e.g. Asia). Omitted = all regions. |
| search | string | Free-text university name search applied by the site. |
| sort_by | string | Sort key: rank, university, overallscore, or indicator_<indicator_id> using an indicator_id from universities[*].indicators. Omitted = rank order. |
| order_by | string | asc or desc; only meaningful with sort_by. |
| country_code | string | Two-letter country code from list_locations.regions[*].countries[*].country_code (e.g. gb). Omitted = all countries. |
| items_per_page | string | Rows per page; values above 100 are clamped to 100. |
{
"type": "object",
"fields": {
"page": "integer 0-based page returned",
"has_more": "boolean, true when a later page exists",
"total_pages": "integer",
"edition_year": "edition year parsed from the ranking title",
"universities": "array of ranked rows: rank, rank_sort, university_id, core_id, name, slug (for get_university_profile), profile_url, region, country, city, logo, overall_score, stars, indicators[] {group, indicator_id, indicator_name, rank, score}",
"ranking_title": "page title of the ranking edition",
"items_per_page": "integer page size honoured by the site",
"total_universities": "integer total rows matching the filters"
},
"sample": {
"data": {
"page": 1,
"has_more": true,
"total_pages": 19,
"edition_year": "2027",
"universities": [
{
"city": "London",
"logo": "https://www.topuniversities.com/sites/default/files/231024034600pm558869KCL-box-red-485-rgb-90x90.jpg",
"name": "King's College London",
"rank": "37",
"slug": "kings-college-london",
"stars": "",
"region": "Europe",
"core_id": "357",
"country": "United Kingdom",
"rank_sort": 37,
"indicators": [
{
"rank": "44",
"group": "Research & Discovery",
"score": "96.3",
"indicator_id": "76",
"indicator_name": "Academic Reputation"
}
],
"profile_url": "https://www.topuniversities.com/universities/kings-college-london",
"overall_score": "85.7",
"university_id": "294029"
}
],
"ranking_title": "QS World University Rankings 2027: Top Global Universities | TopUniversities",
"items_per_page": 5,
"total_universities": 93
},
"status": "success"
}
}About the topuniversities API
World and Subject Rankings
get_world_rankings returns a paginated table of QS World University Rankings for a given year (defaults to the latest edition). Each row in the universities array includes the display rank (which may be tied, e.g. =2, or banded, e.g. 801+), a numeric rank_sort for plain integer ranks, university_id, core_id, name, slug, profile_url, region, country, overall score, and a set of per-indicator scores keyed by indicator ID. You can sort by rank, university, overallscore, or any indicator_<indicator_id> using the sort_by and order_by params. get_subject_rankings follows the same row shape but requires a subject slug from list_subject_rankings and exposes subject-specific indicators such as H-index Citations and Citations per Paper.
Location and Subject Vocabularies
list_locations returns the complete filter vocabulary in one call: a regions array where each region contains countries (with country_code for the country_code filter) and nested cities arrays, plus an edition_years array that flags which year is current. list_subject_rankings lists every published QS subject ranking with its subject slug, display name, and edition_year — pass the slug directly to get_subject_rankings.
University Profiles
get_university_profile accepts a slug from either rankings endpoint and returns the university's name, location, structured address object (streetAddress, addressLocality, addressRegion, postalCode, addressCountry), summary, about text, student_staff_stats (Total students, International students, Total faculty staff), and a current_rankings array listing each QS ranking the university appears in along with its rank. Fields like about, address, and location may be null for some institutions.
The topuniversities API is a managed, monitored endpoint for topuniversities.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when topuniversities.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 topuniversities.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 that ranks institutions head-to-head by a specific QS indicator score.
- Populate a study-abroad directory filtered by region and country using list_locations vocabularies.
- Track year-over-year rank changes for a watchlist of universities across multiple edition years.
- Surface subject-specific rankings (e.g. computer science, engineering) for course recommendation engines.
- Display student-to-faculty ratios and international student counts from get_university_profile for enrollment research tools.
- Aggregate all QS subject rankings a single university appears in using current_rankings from the profile endpoint.
- Filter QS rankings by city to identify top-ranked universities in a specific metropolitan area.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does QS / topuniversities.com offer an official developer API?+
How do tied and banded ranks appear in the response, and how can I sort numerically?+
rank field in the universities array reflects the display string exactly as shown on the site — tied ranks appear as =14 and banded ranks as 801+. When rank is a plain integer, rank_sort holds that integer so you can sort numerically. For custom sorting, pass sort_by=rank (or any indicator_<id>) with order_by=asc or order_by=desc.How does pagination work across the ranking endpoints?+
get_world_rankings and get_subject_rankings use 0-based page indexing. The response always includes total_pages, total_universities, items_per_page, and a has_more boolean so you can walk all pages without guessing offsets.Does the API cover historical ranking editions beyond the latest year?+
get_world_rankings: pass a 4-digit year param using values returned by list_locations.edition_years. Subject rankings via get_subject_rankings do not currently accept a year parameter — only the current edition is available for subject data. You can fork this API on Parse and revise it to add year filtering to the subject rankings endpoint.