---
title: "University Entrance rank score, and an indicative GPA"
method: POST
path: "/v1/ncea-rank-score"
tags: ["Calculators"]
---

# University Entrance rank score, and an indicative GPA

`POST /v1/ncea-rank-score`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/ncea-rank-score`
- Auth: API key in header `X-API-Key`

Turn NCEA credits into the two numbers people need from them.

The asked-for number is a GPA, because a scholarship form or an overseas
university wants one and NZQA issues none. The widely used weighting is
Excellence 4, Merit 3, Achieved 2, credit-weighted, and that is returned as
`indicative_gpa_4_point` with `gpa_is_unofficial` set, because there is no
authoritative conversion and pretending otherwise would be the error.

The number that decides things is `rank_score`. Every New Zealand
university uses the University Entrance rank score to select for
limited-entry programmes: medicine, law, engineering, design. It is the
BEST 80 credits at Level 3 or above, weighted the same way, capped at 320.
Almost nobody asks for it by name, which is why it is returned unasked.

**`credits_ignored` is the field that changes behaviour.** Credits are
counted Excellence first, then Merit, then Achieved, until 80 are used, so
a student with 80 Excellence and 40 Achieved scores exactly the same as one
with 80 Excellence alone. Collecting more Achieved credits is worth
nothing; lifting an existing subject to Merit is worth a great deal.
`next_step` says which case this student is in.

Not Achieved credits are excluded from the rank score entirely and do drag
the indicative GPA down, because that is a mean over everything attempted.

## Request body

- NceaRankScoreRequest
  - `excellence_credits` integer: Level 3 or above credits achieved with Excellence.
  - `merit_credits` integer: Level 3 or above credits achieved with Merit.
  - `achieved_credits` integer: Level 3 or above credits achieved.
  - `not_achieved_credits` integer: Credits attempted and not achieved. They do NOT affect the rank score and they do lower the indicative GPA.

## Response `200`

The rank score out of 320, the credits that counted, and an unofficial 4-point GPA.

- NceaRankScoreResponse
  - `result` NceaRankScoreResult, required
    - `excellence_credits` integer, required: Excellence credits as given.
    - `merit_credits` integer, required: Merit credits as given.
    - `achieved_credits` integer, required: Achieved credits as given.
    - `not_achieved_credits` integer, required: Not Achieved credits as given.
    - `total_credits` integer, required: Everything entered, including Not Achieved.
    - `rank_score` integer, required: The University Entrance rank score, out of 320. This is the number New Zealand universities use to select for limited-entry courses.
    - `rank_score_max` integer, required: 320, being 80 credits at 4 points.
    - `credits_counted` integer, required: How many of the best 80 were used.
    - `credits_ignored` integer, required: Achieving credits that fell outside the best 80 and count for nothing. Usually a surprise, and the reason improving a grade beats collecting more credits.
    - `rank_score_working` string, required: The rank score calculation written out.
    - `indicative_gpa_4_point` number, required: An UNOFFICIAL 4-point GPA, credit-weighted at Excellence 4, Merit 3, Achieved 2. NZQA issues no GPA.
    - `gpa_is_unofficial` boolean, required: Always true. NZQA does not issue a GPA.
    - `next_step` string, required: What would actually raise the rank score for this student.
    - `excludes` string[], required: What this does not cover.
  - `disclaimer` string, required: Scope and limits of this calculation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)