Response Envelope

Every endpoint, without exception, returns the same JSON envelope. Clients can parse the outer shape without knowing which endpoint was called.

Success response

{
  "country": "GH",   // ISO 3166-1 alpha-2 country code
  "count": 2,        // number of records in data array
  "data": [          // always an array, even for count=1
    { ... },
    { ... }
  ]
}

Error response

{
  "error": "unsupported country code",
  "code":  "INVALID_COUNTRY",
  "status": 400
}

Notes

• data is always an array - never a bare object
• country is always the resolved code, even if a random country was selected
• count reflects the actual number of records returned, not the requested count