This is a a GraphQL API that provides information about places from the South African National Census of 2011.
The information that is available here is the same information that is displayed at https://census2011.adrianfrith.com.
The API is available by POST to https://census-api.frith.dev/graphql.
See the examples below or the full schema listed at the end of this file.
The name search on the census site is driven by the following query, which requests the code, name, place type, province, population and area.
query ($name: String!) {
placesByName: places(name: $name) {
code
name
type { name descrip }
province { code name }
population
area
}
}The result of this query looks like the following (in this case the value of $name was "pine").
{
"data": {
"places": [
{
"code": "599116",
"name": "Pinetown",
"type": {
"name": "mainplace",
"descrip": "Main Place"
},
"province": {
"code": "5",
"name": "KwaZulu-Natal"
},
"population": 144026,
"area": 86.15482956387405
},
// ... 22 more results ...
]
}
}This is the query used to populate the place page on the census site; it includes all the information available except the place geometry.
query ($code: String!) {
place(code: $code) {
code
name
type { name descrip }
fullParents {
code
name
type { name descrip }
}
children {
code
name
type { name descrip }
population
area
}
population
households
area
variables {
variable { id name }
values { label value }
}
bbox
}
}The result looks like the following (in this case the value of $code was "199041026").
{
"data": {
"place": {
"code": "199041026",
"name": "Pinelands",
"type": {
"name": "subplace",
"descrip": "Sub Place"
},
"fullParents": [
{
"code": "1",
"name": "Western Cape",
"type": {
"name": "province",
"descrip": "Province"
}
},
{
"code": "199",
"name": "City of Cape Town",
"type": {
"name": "metro",
"descrip": "Metropolitan Municipality"
}
},
{
"code": "199041",
"name": "Cape Town",
"type": {
"name": "mainplace",
"descrip": "Main Place"
}
}
],
"children": [
{
"code": "1990345",
"name": "Small Area 0345",
"type": {
"name": "sa",
"descrip": "Small Area"
},
"population": 324,
"area": 0.13688033729831153
},
// ... 27 more small areas ...
],
"population": 14198,
"households": 4915,
"area": 5.855472074207003,
"variables": [
{
"variable": {
"id": "1",
"name": "Gender"
},
"values": [
{
"label": "Male",
"value": 6602
},
{
"label": "Female",
"value": 7596
}
]
},
// ... 3 more variables ...
],
"bbox": [
18.490539049000063,
-33.949555104999945,
18.528193225000052,
-33.91947424799997
]
}
}
}The following query takes a pair of coordinates and finds the subplace that contains that point.
query ($latitude: Float!, $longitude: Float!) {
places(
type: "subplace",
coordinates: { latitude: $latitude, longitude: $longitude }
)
{
code
name
}
}The result looks like the following (in this case $latitude was -33.934 and $longitude was 18.415).
{
"data": {
"places": [
{
"code": "199041044",
"name": "Oranjezicht"
}
]
}
}# A read-only schema for South African census data.
type Query {
# Get multiple places by name, type, and/or geographical coordinates.
places(name: String, type: String, coordinates: CoordinatesInput): [Place]
# Get a single place by code.
place(code: String!): Place
# Get all place types (Province, Muni, Main Place, etc.)
placeTypes: [PlaceType]
# Get a single place type by the short name (e.g. "metro", "subplace", etc.).
placeType(name: String!): PlaceType
# Get all variables
variables: [Variable]
# Get a variable by ID
variable(id: ID!): Variable
}
# A place (a province, a municipality, a main place, etc.)
type Place {
# The unique code assigned to the place by Stats SA.
code: String!
# The type of place (Province, Muni, Main Place, etc.)
type: PlaceType!
# The name of the place.
name: String
# The province in which the place is located.
province: Place
# The immediate parent place containing this place.
parent: Place
# The population of the place.
population: Int
# The number of households in the place.
households: Int
# The area of the place in square km.
area: Float
# Direct child places contained within this place.
children: [Place]
# All parent places within which this place is contained.
fullParents: [Place]
# The geometry of the place as a GeoJSON object.
geom: JSON
# The bounding box of the place [west, south, east, north].
bbox: [Float]
# Details of all demographic variables for the place.
variables: [PlaceVariable]
# Details of a single demographic variable for the place.
variable(variableId: ID!): PlaceVariable
}
# A type of place (Province, Muni, Main Place, etc.).
type PlaceType {
# Short code (e.g. "metro", "subplace", etc.).
name: String!
# Full descriptive title of the place (e.g. "Metropolitan Municipality").
descrip: String
}
# A demograhic variable (e.g. Gender, Age).
type Variable {
# Unique ID.
id: ID!
# Name of the variable (e.g. "Gender").
name: String!
# Possible values (e.g. "Male", "Female").
labels: [String]
}
# Details about a demographic variable for a particular place.
type PlaceVariable {
# The variable
variable: Variable
# The values of that variable in that place.
values: [LabelValue]
}
# A pair of a label and a value.
type LabelValue {
label: String!
value: Int!
}
# Input value for the coordinate search
input CoordinatesInput {
latitude: Float!
longitude: Float!
}
scalar JSON