Skip to content
U4SUniversity4Students
Menu

Explore University4Students

Universities, student life, independence and practical guides.

API reference

Version v1. Key-authenticated, bounded, and currently switched off.

Base URL

https://university4students.com/api/v1/ — the version is in the path and always will be. An endpoint without one is not part of this API.

The machine-readable description is at /api/v1/openapi.json. It is generated from the same constants the code enforces, so it cannot describe an endpoint that does not exist.

Authentication

Send your key as Authorization: Bearer <key>. This key is shown once and is not stored. U4S keeps a SHA-256 of it, which is enough to recognise it and useless to anybody who takes the table. If it is lost, revoke it and mint another — there is no operation that reveals it again, because a key U4S could show you is a key U4S is holding.

Rotating a key mints a new one AND revokes the old one. Both happen or neither does — a new key beside a still-working old one is not a rotation, and is how a leaked key keeps working long after somebody believes they replaced it.

Scopes

public_read
The same facts the public site publishes, and nothing else.
institution_read
One institution’s own operational data. Never another institution’s.
institution_export
Bulk export of that institution’s own data, subject to suppression.

Resources

  • GET /api/v1/countries
  • GET /api/v1/cities
  • GET /api/v1/universities
  • GET /api/v1/subjects
  • GET /api/v1/programmes
  • GET /api/v1/scholarships
  • GET /api/v1/admissions
  • GET /api/v1/housing

Pagination

limit defaults to 50 and may not exceed 200. A larger value is rejected rather than quietly reduced, so a caller always knows what it asked for. Follow page.nextCursor for the next page.

Rate limits

Per key, per hour: public_read 600, institution_read 1200, institution_export 60.

Limits are per key per hour. These facts change when U4S re-reads a source, which is days apart, so polling faster returns the same values — cache the response rather than raising the limit.

Errors

Every error is JSON with a stable error code and a message a person can act on.

  • api_disabled — The University Data API is not enabled in this environment.
  • no_key — No API key was presented. Send it as "Authorization: Bearer <key>".
  • malformed_key — That is not a U4S API key. Keys begin with u4s_live_ or u4s_test_.
  • unknown_key — That key is not recognised.
  • revoked_key — That key has been revoked and will not work again. Issue a new one.
  • expired_key — That key has expired. Rotate it to get a working replacement.

What this API will never serve

Listed rather than omitted, because finding out after you have integrated is worse than reading it now. None of these has a serialiser at any tier, for any price.

  • Raw interaction events. They carry no identifier and are still nobody’s business.
  • Aggregates below the suppression threshold, in any form.
  • Who claimed an institution, and what they wrote.
  • A reviewer’s private notes.
  • Anything to do with authentication.
  • Proposals before a U4S editor has integrated them.
  • The audit trail. It exists to hold U4S to account, not to be published.
  • Student inquiries. They are a person writing to one institution.
  • Who pays U4S for what.
  • Raw interaction events. They are never exposed, to anybody, at any tier.
  • Who claimed an institution. That is a person, and never an API resource.
  • A reviewer’s private notes. They exist so a reviewer can think in private.
  • Another institution’s operational data. No key reaches it.
  • A ranking position. U4S publishes none, so there is nothing to read.

No SLA

U4S offers no service level agreement for this API. There is no uptime commitment, no support response time and no compensation, because none has been agreed with anybody — and publishing a number nobody is accountable for would be worse than saying so.

Back to developers