/the/rankings/table

POST /api/the/rankings/table

Price: 20 credits

Read one edition of a Times Higher Education ranking table

How to use it

One call reads a whole edition of one Times Higher Education table, so pass the widest `count` you actually want rather than paging. Editions go back to 2011 for the world and several subject tables; omit `year` to get the newest one. The tables are published with differing score columns, so read `scores[].key` instead of expecting a fixed set, and note that the impact ranking carries `sdg_scores` and only an overall score. Institutions with the rank 'Reporter' are listed but not ranked and carry no scores — set `ranked_only` to drop them. `institution_id` is stable across editions and is what to join a time series on; it is a Times Higher Education id and has no counterpart at any other ranking publisher.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• ranking string — Which Times Higher Education ranking table to read. (default: "world_university_rankings"; one of: "world_university_rankings", "world_impact_rankings", "asia_university_rankings", "arabic_university_rankings", "latin_america_rankings", "arts_humanities_rankings", "business_economics_rankings", "clinical_pre_clinical_health_ran", "computer_science_rankings", "education_rankings", "engineering_technology_rankings", "law_rankings", "life_sciences_rankings", "physical_sciences_rankings", "psychology_rankings", "social_sciences_rankings")
• year integer nullable — Edition year of the table. Omitted, the newest edition Times Higher Education publishes for this ranking is used. A year the ranking was not published returns 412. (examples: 2026, 2011; min: 2011; max: 2030)
• country string nullable — Keep only institutions in this country, given as an ISO 3166-1 alpha-3 code or as the country name the table itself prints. (examples: "GBR", "Japan"; minLength: 1)
• name string nullable — Keep only institutions whose name or alternative name contains this text. (examples: "technology", "Oxford"; minLength: 1)
• subject string nullable — Keep only institutions that teach this subject, named exactly as the table prints it, for example 'Computer Science' or 'Art, Performing Arts & Design'. (examples: "Computer Science"; minLength: 1)
• ranked_only boolean — Drop the institutions Times Higher Education lists but does not rank, which carry the rank 'Reporter' and no scores. (default: false)
• count integer required — Max number of institutions to return. (examples: 50; min: 1; max: 3500)

Response

• @type string (default: "TheRankedInstitution")
• id string required
• institution_id string required
• node_id string nullable
• ranking string required
• year integer required
• name string required
• alternative_name string nullable
• alias string nullable
• profile_url string nullable
• rank string nullable
• rank_order integer nullable
• is_ranked boolean (default: false)
• country string nullable
• country_code string nullable
• record_type string nullable
• is_closed boolean (default: false)
• is_disabled boolean (default: false)
• is_unaccredited boolean (default: false)
• scores array (default: [])
  • @type string (default: "TheRankingScore")
  • key string required
  • name string nullable
  • score number nullable
  • rank integer nullable
• sdg_scores array (default: [])
  • @type string (default: "TheSdgScore")
  • sdg_number integer required
  • name string nullable
  • score number nullable
  • rank integer nullable
  • rank_display string nullable
• subjects array (default: [])
• student_count integer nullable
• students_per_staff number nullable
• international_student_percent number nullable
• female_student_percent number nullable
• male_student_percent number nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — This ranking was not published for that year Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.