SHS PLACEMENT API

Build school-selection tools for BECE candidates.

Every year, BECE candidates in Ghana choose eight senior high schools on CSSPS. SukuuData gives you the official 2026 GES register as clean JSON and checks a candidate's choices against the 2026 selection rules, so your app can help families choose well before they submit.

What's in the register

• 1,082 schools from the GES Register of Courses for Public SHS, TVET and Pilot Private Schools, 2026: 94 Category A, 259 Category B, 646 Category C and 83 pilot private schools.
• For each school: its 7-digit CSSPS code, category, type (SHS, SHTS or TVET), gender, day and boarding options, and programmes, from General Science to STEM, Languages and 44 TVET trades.
• Schools with facilities for visually or hearing-impaired candidates.
• Map coordinates for most schools, so you can search by distance from a candidate's home.

GES published the 2026 register as a PDF. We extracted it and corrected the codes it misprinted; each response gives the register year it comes from.

Find schools a candidate can attend

GET /secondary-schools filters by programme, category, region or district, day or boarding, and the candidate's gender. Add lat and lng to get the nearest schools first, with distances. This finds boarding schools offering STEM that a girl can attend:

curl "https://api.sukuudata.com/api/v1/secondary-schools?programme=503&studentGender=female&residential=BOARDING" \
  -H "X-API-Key: YOUR_KEY"

const params = new URLSearchParams({
  programme: "503",          // STEM
  studentGender: "female",   // only schools she can attend
  residential: "BOARDING",
});
const res = await fetch(`https://api.sukuudata.com/api/v1/secondary-schools?${params}`, {
  headers: { "X-API-Key": process.env.SUKUUDATA_KEY },
});
const { data } = await res.json();

res = requests.get(
    "https://api.sukuudata.com/api/v1/secondary-schools",
    params={"programme": "503", "studentGender": "female", "residential": "BOARDING"},
    headers={"X-API-Key": os.environ["SUKUUDATA_KEY"]},
)
schools = res.json()["data"]

Look up one school by its CSSPS code with GET /secondary-schools/{code}, and list every programme code with GET /programmes.

Check a candidate's eight choices

POST /placement/validate takes the choices in order of preference and returns errors (rules the form breaks) and warnings (advice, such as a day school far from home). It checks:

• exactly 8 choices, at most 5 boarding and 3 day;
• category limits: at most 2 Category A schools, and at most 3 Category B (2 boarding, 1 day);
• no school chosen twice;
• that each school offers the chosen programme and residential status, and admits the candidate's gender;
• with a home location, that day schools are within reach.

A real example: a boy picks three Category A schools, one of which is a girls' school.

curl https://api.sukuudata.com/api/v1/placement/validate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "studentGender": "MALE",
    "choices": [
      { "csspsCode": "0010121", "programme": "502", "residential": "BOARDING" },
      { "csspsCode": "0010110", "programme": "502", "residential": "BOARDING" },
      { "csspsCode": "0020301", "programme": "502", "residential": "BOARDING" },
      { "csspsCode": "0021303", "programme": "502", "residential": "BOARDING" },
      { "csspsCode": "0030109", "programme": "502", "residential": "BOARDING" },
      { "csspsCode": "0030403", "programme": "502", "residential": "DAY" },
      { "csspsCode": "0070503", "programme": "502", "residential": "DAY" },
      { "csspsCode": "0030402", "programme": "502", "residential": "DAY" }
    ]
  }'

The response names both problems and the choice each one is about:

{
  "success": true,
  "data": {
    "valid": false,
    "errors": [
      {
        "code": "GENDER_MISMATCH",
        "message": "Choice 3: Aburi Girls' Senior High School is a girls' school.",
        "choice": 3
      },
      {
        "code": "CATEGORY_A_LIMIT",
        "message": "At most 2 Category A schools; 3 given."
      }
    ],
    "warnings": [],
    "summary": {
      "total": 8, "boarding": 5, "day": 3,
      "byCategory": {
        "A": { "total": 3, "boarding": 3, "day": 0 },
        "B": { "total": 2, "boarding": 2, "day": 0 },
        "C": { "total": 3, "boarding": 0, "day": 3 },
        "PILOT_PRIVATE": { "total": 0, "boarding": 0, "day": 0 }
      }
    },
    "choices": [ … each choice with its school, programme and distance … ]
  }
}

The rules, as data

GET /placement/rules returns the 2026 CSSPS selection rules (choice counts, category limits and guidance notes) with a link to the official guidelines, so your app can show them to candidates and stay in step when the rules change each year.

Ideas to build

• A school-selection assistant for parents: pick a programme and town, see eligible schools, check the final eight.
• A checker for JHS head teachers to review a whole class's forms before the upload deadline.
• WhatsApp or USSD bots for families without smartphones or data.
• Career explorers that map goals such as engineering or nursing to programmes and schools.