Hotcourses Abroad APIhotcoursesabroad.com ↗
Access the Hotcourses Diversity Index: ranked universities by international student nationalities, with per-university nationality breakdowns and ISO country codes.
What is the Hotcourses Abroad API?
This API exposes two endpoints covering the Hotcourses Diversity Index (HDI), returning ranked university records across all study destinations or filtered by country, plus per-university breakdowns of international student nationalities with ISO 3166-1 alpha-2 codes. The list_university_diversity endpoint pages through up to the full HDI ranking, while get_university_nationalities returns every nationality the index lists for a single university, including share rank and tie flags.
curl -X GET 'https://api.parse.bot/scraper/cdfbe225-1a6d-47a0-8647-6ecf9bdd958c/list_university_diversity?country=australia' \ -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 hotcoursesabroad-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: Hotcourses Abroad diversity SDK — bounded, re-runnable."""
from parse_apis.hotcoursesabroad_com_api import (
HotcoursesAbroad, Destination, UniversityNotFound,
)
client = HotcoursesAbroad()
# Browse the top-ranked universities in Australia by diversity.
for uni in client.universities.list(country=Destination.AUSTRALIA, limit=5):
approx = "~" if uni.international_students_approximate else ""
print(f"#{uni.rank} {uni.university_name} — {uni.nationalities_count} nationalities, "
f"{approx}{uni.international_students} intl students")
# Drill into the first result's nationality breakdown.
top = client.universities.list(country=Destination.AUSTRALIA, limit=1).first()
if top is not None:
try:
for nat in top.nationalities.list(limit=10):
pct = f"{nat.share_percent:.1f}%" if nat.share_percent is not None else "n/a"
print(f" {nat.rank}. {nat.nationality} ({nat.nationality_iso}) — {pct}")
except UniversityNotFound:
print(f"University {top.university_id} no longer listed")
# Point-construct a university by known id and fetch its nationalities.
monash = client.university(university_id="72222")
for nat in monash.nationalities.list(limit=3):
print(f" {nat.nationality}: {nat.share_percent}%")
print("exercised: universities.list / nationalities.list / university()")
Returns one page (20 universities) of the Hotcourses Diversity Index ranking, ordered by number of international student nationalities (rank ties share a rank). Each record carries the university's site id, destination country label and ISO 3166-1 alpha-2 code, count of nationalities, international student headcount (flagged when the site marks it approximate), the relative diversity bar percentage, review count and profile URL. Without a country filter the ranking spans every destination the site covers (Australia, New Zealand, UK, USA). One request per call; total_universities and total_pages come from the site and has_more tells you whether page+1 exists. Omitting page returns the first page; a page beyond total_pages returns an empty universities array.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page of 20 universities. |
| country | string | Study destination to restrict the ranking to. Omitted = all destinations combined. |
{
"type": "object",
"fields": {
"page": "integer page returned",
"has_more": "boolean, true when a later page exists",
"total_pages": "integer number of pages for this filter",
"universities": "array of ranked university records: rank, university_id (use with get_university_nationalities), university_name, country, country_iso (ISO 3166-1 alpha-2), nationalities_count, international_students, international_students_approximate, diversity_bar_percent, reviews_count, profile_url",
"country_filter": "destination slug applied, or null when all destinations were requested",
"total_universities": "integer total universities in this ranking"
},
"sample": {
"data": {
"page": 2,
"has_more": true,
"total_pages": 5,
"universities": [
{
"rank": 21,
"country": "Australia",
"country_iso": "AU",
"profile_url": "https://www.hotcoursesabroad.com/study/australia/school-college-university/edith-cowan-university/72216/international.html",
"reviews_count": 21,
"university_id": "72216",
"university_name": "Edith Cowan University",
"nationalities_count": 101,
"diversity_bar_percent": 72,
"international_students": 6011,
"international_students_approximate": true
}
],
"country_filter": "australia",
"total_universities": 84
},
"status": "success"
}
}About the Hotcourses Abroad API
University Diversity Ranking
The list_university_diversity endpoint returns pages of 20 universities from the Hotcourses Diversity Index, ordered by number of distinct international student nationalities. Each record includes a rank (ties share the same rank value), university_id, university_name, country, and country_iso (ISO 3166-1 alpha-2). The response also carries total_universities, total_pages, has_more, and the country_filter slug applied. Use the country parameter to restrict results to a single study destination — omit it to query the combined global ranking. The page parameter is 1-based; each call returns up to 20 records.
Per-University Nationality Breakdown
The get_university_nationalities endpoint accepts a university_id — the numeric ID returned by list_university_diversity — and returns the full nationality breakdown for that institution. The nationalities array is ordered by share rank and includes each entry's rank, tied boolean, nationality label as published by the site, and nationality_iso code. The response also provides nationalities_count, giving the total number of distinct nationalities listed for that university.
Coverage and Filtering
Destination filtering in list_university_diversity uses a country slug rather than a free-text name or ISO code — available slugs correspond to the study destinations Hotcourses Abroad tracks in the HDI. There is no endpoint for listing available destination slugs directly; slugs appear in country_filter fields of prior responses. The HDI covers universities that report international enrollment data to Hotcourses Abroad, so institutions without reported diversity data are not included in the ranking.
The Hotcourses Abroad API is a managed, monitored endpoint for hotcoursesabroad.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hotcoursesabroad.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 hotcoursesabroad.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?+
- Rank universities by international student diversity for a study-abroad comparison tool, using
rankandnationalities_countfields. - Filter the HDI ranking by destination country to surface the most internationally diverse universities in a specific region.
- Map institutional diversity geographically by pairing
country_isocodes from university records with mapping libraries. - Drill into a specific university's
nationalitiesarray to display which countries its international students come from. - Compare diversity profiles of two universities by calling
get_university_nationalitiesfor each and diffing their nationality arrays. - Build a country-level aggregation of nationality diversity by paginating
list_university_diversitywith acountryfilter. - Flag nationality tie situations in ranking displays using the
tiedboolean from the nationality breakdown endpoint.
| 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 Hotcourses Abroad have an official developer API?+
What does `list_university_diversity` return and how does pagination work?+
page (1-based). The response includes has_more to indicate whether additional pages exist, total_pages for the current filter, and total_universities for the full count. Supply the country parameter with a destination slug to restrict results to one study destination.Does the nationality breakdown include the percentage share each nationality represents?+
get_university_nationalities response includes rank and tied fields for each nationality, reflecting relative share order, but the endpoint description notes the site publishes an exact percentage share only in some cases — the field may be absent for certain records. The array order and rank fields are reliable indicators of relative size. You can fork this API on Parse and revise it to surface percentage values where the source publishes them.Is there an endpoint to list all available study destination slugs for the `country` filter?+
country_filter field of list_university_diversity responses, but there is no dedicated endpoint that enumerates all valid slugs. You can fork this API on Parse and revise it to add a destinations-listing endpoint.