Population/API v2

Population by province

GET/api/v2/population/subdivisions

Good to know. RGPH 2024 and HCP historical series. See meta for each series’ source and date.

Understand the context

RGPH is the population census run by HCP, Morocco’s statistics office. A resident is not necessarily a Moroccan citizen. Reading example: 100 residents, including 95 Moroccan nationals and 5 foreign nationals, means a total of 100; do not add them again. These figures are illustrative.

Read the response

data: The requested results, as an object or an array.

meta: Dataset sources, license and dates. null means unknown or unavailable.

meta.pagination: Lists: 100 results by default, 500 maximum. Use limit and offset; meta.pagination.next_offset is null on the last page.

Illustrative example: With limit=10 and offset=0, the first page holds at most 10 results. If next_offset is 10, request the next page with offset=10 and the same filters. Stop when next_offset is null.

API v2 is the canonical path. Older /api/v1 paths remain compatibility aliases for the currently published behavior, including pagination; no removal date is scheduled.

Response fields 14

[] means each item in a list. null means unknown or unavailable, never zero. The guide language does not translate source values.

dataobject[]

Requested result: a single object or a list.

data[].codestring

MoroccoAPI resource identifier; use it in the corresponding resource URLs.

data[].hcp_codestring

Code from HCP, Morocco’s national statistics office. Keep it as text to preserve leading zeros.

data[].typestring

Kind of resource. Possible values are listed below.

Accepted values: "province_or_prefecture"

data[].administrative_typestring

province or prefecture: two categories at the same administrative level, below a region.

Accepted values: "province" "prefecture"

data[].nameobject

Resource name, grouped by language where applicable.

data[].name.arstring

Arabic value; null when no translation is provided.

data[].name.frstring

French value; null when no translation is provided.

data[].name.enstring | null

English value; null when no translation is provided.

data[].region_codestring

Identifier of the parent region, Morocco’s first administrative level.

data[].populationinteger

Total census residents in this administrative unit.

data[].moroccansinteger

Number of residents with Moroccan nationality in the stated area.

data[].foreignersinteger

Number of foreign-national residents in the stated area.

data[].householdsinteger

Number of census households; a household may contain one or more people.

Data structure

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "hcp_code",
          "type",
          "administrative_type",
          "name",
          "region_code",
          "population",
          "moroccans",
          "foreigners",
          "households"
        ],
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-+[a-z0-9]+)*$"
          },
          "hcp_code": {
            "type": "string",
            "pattern": "^[0-9]{2}\\.[0-9]{3}$"
          },
          "type": {
            "enum": [
              "province_or_prefecture"
            ]
          },
          "administrative_type": {
            "enum": [
              "province",
              "prefecture"
            ]
          },
          "name": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "ar",
              "fr",
              "en"
            ],
            "properties": {
              "ar": {
                "type": "string"
              },
              "fr": {
                "type": "string"
              },
              "en": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "string",
                    "nullable": true,
                    "enum": [
                      null
                    ]
                  }
                ]
              }
            }
          },
          "region_code": {
            "type": "string"
          },
          "population": {
            "type": "integer",
            "minimum": 0
          },
          "moroccans": {
            "type": "integer",
            "minimum": 0
          },
          "foreigners": {
            "type": "integer",
            "minimum": 0
          },
          "households": {
            "type": "integer",
            "minimum": 0
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "dataset",
        "total",
        "license",
        "retrieved_at",
        "transformation_version",
        "sources",
        "pagination"
      ],
      "properties": {
        "dataset": {
          "enum": [
            "subdivision-population"
          ]
        },
        "total": {
          "type": "integer",
          "minimum": 0
        },
        "license": {
          "enum": [
            "CC-BY-4.0"
          ]
        },
        "retrieved_at": {
          "enum": [
            "2026-10-05"
          ]
        },
        "transformation_version": {
          "enum": [
            "2.0.0"
          ]
        },
        "sources": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "dataset",
              "producer",
              "source_url",
              "resource_url",
              "license",
              "source_updated_at"
            ],
            "properties": {
              "dataset": {
                "type": "string"
              },
              "producer": {
                "type": "string"
              },
              "source_url": {
                "type": "string",
                "format": "uri"
              },
              "resource_url": {
                "type": "string",
                "format": "uri"
              },
              "license": {
                "enum": [
                  "CC-BY-4.0"
                ]
              },
              "source_updated_at": {
                "type": "string",
                "format": "date"
              }
            }
          }
        },
        "pagination": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "limit",
            "offset",
            "count",
            "has_more",
            "next_offset"
          ],
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            },
            "offset": {
              "type": "integer",
              "minimum": 0,
              "maximum": 2147483647
            },
            "count": {
              "type": "integer",
              "minimum": 0,
              "maximum": 500
            },
            "has_more": {
              "type": "boolean"
            },
            "next_offset": {
              "anyOf": [
                {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 2147483647
                },
                {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    null
                  ]
                }
              ]
            }
          }
        }
      }
    }
  }
}

Sources and pagination 19

metaobject

Result context: sources, dates, license and pagination where applicable.

meta.datasetstring

Name of the dataset for this result or source.

Accepted values: "subdivision-population"

meta.totalinteger

Number of matching records before pagination; not the size of this page.

meta.licensestring

Reuse license. mixed means licenses differ: inspect each source.

Accepted values: "CC-BY-4.0"

meta.retrieved_atstring

Date the project retrieved the source file; not the observation date.

Accepted values: "2026-10-05"

meta.transformation_versionstring

Version of the dataset conversion rules; separate from the API version.

Accepted values: "2.0.0"

meta.sourcesobject[]

Sources used for this result, with their publishers and licenses.

meta.sources[].datasetstring

Name of the dataset for this result or source.

meta.sources[].producerstring

Organization publishing the original data.

meta.sources[].source_urlstring

Source publication or dataset landing page.

meta.sources[].resource_urlstring

Link to the actual file or resource used.

meta.sources[].licensestring

Reuse license. mixed means licenses differ: inspect each source.

Accepted values: "CC-BY-4.0"

meta.sources[].source_updated_atstring

Last update reported by the source; not the retrieval date.

meta.paginationobject

Information for reading a collection one page at a time.

meta.pagination.limitinteger

Requested maximum records per page: default 100, maximum 500.

meta.pagination.offsetinteger

Matching records skipped before this page, after filtering. The first page starts at 0.

meta.pagination.countinteger

Number of records actually returned on this page.

meta.pagination.has_moreboolean

true when another page of records remains.

meta.pagination.next_offsetinteger | null

Use as offset for the next page; null at the end. Keep the same filters.

Errors

400: Invalid or missing parameter.

Errors return error.code, error.message and error.request_id.

errorobject: Details of a failed request; replaces data and meta.
error.codestring: Stable error code, such as RESOURCE_NOT_FOUND; use it in application logic.
error.messagestring: Human-readable error explanation; use code for application logic.
error.request_idstring: Identifier for this request, useful when reporting a problem.

Population by province

Parameters

Your request