{
  "openapi": "3.1.0",
  "info": {
    "title": "data-geo",
    "version": "1.5.0",
    "description": "Open geospatial datasets re-published cloud-native, with an API. Datasets: WorldPop's gridded population (R2025A, 100 m, 2015–2030), with totals, point, polygon and catchment queries, each for one year or several (with the change between them), and optionally broken down by sex and age group with demographic indicators (WorldPop's age and sex structures, same release). Data © WorldPop, R2025A v1, CC BY 4.0: cite WorldPop for every figure (population doi:10.5258/SOTON/WP00839, age and sex WP00841, under 18 WP00847; full citations at /worldpop/how-it-works#licence-and-citation). And LandScan Mosaic Time Series (Oak Ridge National Laboratory, v1.0, 3 arc-second ambient population, 1975–2024), with point, polygon and catchment: CC BY 4.0: cite Zimmer et al. (2026), LandScan Mosaic Time Series, Version 1.0, Oak Ridge National Laboratory, doi:10.48690/lsm/zew2-1n91. Files are read directly by HTTP range; see /llms.txt. Limits: 2,000 API calls an hour per IP, no key; every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds), and past the limit the answer is 429 with Retry-After.",
    "license": {
      "name": "Data: CC BY 4.0 (WorldPop; LandScan Mosaic, ORNL)",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://data-geo.baobabtech.app"
    }
  ],
  "paths": {
    "/v1": {
      "get": {
        "operationId": "index",
        "summary": "Endpoints and links, as JSON",
        "responses": {
          "200": {
            "description": "Index"
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog": {
      "get": {
        "operationId": "catalog",
        "summary": "Datasets, releases, years and files",
        "responses": {
          "200": {
            "description": "catalog.json"
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/worldpop/totals": {
      "get": {
        "operationId": "worldpopTotals",
        "summary": "Population of every administrative unit of a country at one level",
        "description": "From admin_totals.parquet. A 100 m cell counts when its centre is inside the unit. Units are geoBoundaries gbOpen. With groups, also from agesex/admin_totals/{year}.parquet: the same units, the same rule.",
        "parameters": [
          {
            "name": "iso3",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{3}$"
            },
            "example": "KEN",
            "description": "ISO 3166-1 alpha-3 country code"
          },
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ADM0",
                "ADM1",
                "ADM2"
              ],
              "default": "ADM1"
            }
          },
          {
            "$ref": "#/components/parameters/year"
          },
          {
            "$ref": "#/components/parameters/years"
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "r2025a",
              "pattern": "^r\\d{4}[a-z](/_test)?$"
            },
            "description": "The release; default r2025a. r2025a/_test is the two-country test set (Ethiopia and Kenya, age and sex for every year); age and sex for the default release cover 2015, 2020, 2025 and 2030."
          },
          {
            "$ref": "#/components/parameters/groups"
          },
          {
            "$ref": "#/components/parameters/indicators"
          }
        ],
        "responses": {
          "200": {
            "description": "Units",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "iso3": {
                      "type": "string"
                    },
                    "level": {
                      "type": "string"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "units": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "shape_id": {
                            "type": "string"
                          },
                          "shape_name": {
                            "type": "string"
                          },
                          "population": {
                            "type": "number"
                          },
                          "groups": {
                            "$ref": "#/components/schemas/Groups"
                          },
                          "years": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/YearFigure"
                            },
                            "description": "With `years`: one entry per year"
                          },
                          "change": {
                            "$ref": "#/components/schemas/Change"
                          },
                          "peak": {
                            "$ref": "#/components/schemas/Peak"
                          },
                          "indicators": {
                            "$ref": "#/components/schemas/Indicators"
                          }
                        }
                      }
                    },
                    "group_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "source": {
                      "type": "string"
                    },
                    "indicator_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/worldpop/total": {
      "get": {
        "operationId": "worldpopTotal",
        "summary": "Population of one administrative unit",
        "parameters": [
          {
            "name": "iso3",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z]{3}$"
            },
            "example": "KEN",
            "description": "ISO 3166-1 alpha-3 country code"
          },
          {
            "name": "unit",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "geoBoundaries shapeID, as /totals returns it"
          },
          {
            "$ref": "#/components/parameters/year"
          },
          {
            "$ref": "#/components/parameters/years"
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "r2025a",
              "pattern": "^r\\d{4}[a-z](/_test)?$"
            },
            "description": "The release; default r2025a. r2025a/_test is the two-country test set (Ethiopia and Kenya, age and sex for every year); age and sex for the default release cover 2015, 2020, 2025 and 2030."
          },
          {
            "$ref": "#/components/parameters/groups"
          },
          {
            "$ref": "#/components/parameters/indicators"
          }
        ],
        "responses": {
          "200": {
            "description": "One unit with its boundary source and licence; with groups, its breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "iso3": {
                      "type": "string"
                    },
                    "level": {
                      "type": "string"
                    },
                    "shape_id": {
                      "type": "string"
                    },
                    "shape_name": {
                      "type": "string"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "population": {
                      "type": "number"
                    },
                    "groups": {
                      "$ref": "#/components/schemas/Groups"
                    },
                    "group_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "boundary_source": {
                      "type": "string"
                    },
                    "boundary_year": {
                      "type": "string"
                    },
                    "boundary_license": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "years": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YearFigure"
                      },
                      "description": "With `years`: one entry per year"
                    },
                    "change": {
                      "$ref": "#/components/schemas/Change"
                    },
                    "peak": {
                      "$ref": "#/components/schemas/Peak"
                    },
                    "indicators": {
                      "$ref": "#/components/schemas/Indicators"
                    },
                    "indicator_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "description": " With groups, also from agesex/admin_totals/{year}.parquet: the same units, the same rule."
      }
    },
    "/v1/worldpop/point": {
      "get": {
        "operationId": "worldpopPoint",
        "summary": "People in the 100 m cell under a point",
        "parameters": [
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 38.7578
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 9.03
          },
          {
            "$ref": "#/components/parameters/year"
          },
          {
            "$ref": "#/components/parameters/years"
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "r2025a",
              "pattern": "^r\\d{4}[a-z](/_test)?$"
            },
            "description": "The release; default r2025a. r2025a/_test is the two-country test set (Ethiopia and Kenya, age and sex for every year); age and sex for the default release cover 2015, 2020, 2025 and 2030."
          },
          {
            "$ref": "#/components/parameters/groups"
          },
          {
            "$ref": "#/components/parameters/indicators"
          }
        ],
        "responses": {
          "200": {
            "description": "population (and groups) are null where the cell has no value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lon": {
                      "type": "number"
                    },
                    "lat": {
                      "type": "number"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "file": {
                      "type": "string"
                    },
                    "population": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "groups": {
                      "$ref": "#/components/schemas/Groups"
                    },
                    "group_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "cell": {
                      "type": "object"
                    },
                    "source": {
                      "type": "string"
                    },
                    "years": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YearFigure"
                      },
                      "description": "With `years`: one entry per year"
                    },
                    "change": {
                      "$ref": "#/components/schemas/Change"
                    },
                    "peak": {
                      "$ref": "#/components/schemas/Peak"
                    },
                    "indicators": {
                      "$ref": "#/components/schemas/Indicators"
                    },
                    "indicator_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "description": "The value of one 100 m cell. With groups, read from the age and sex file, whose band 1 is the same population value."
      }
    },
    "/v1/worldpop/polygon": {
      "post": {
        "operationId": "worldpopPolygon",
        "summary": "People inside any polygon, exactly",
        "description": "A 100 m cell counts when its centre is inside the polygon (even-odd: holes and multipolygons work). Answered from the sum pyramid: 10 km and 1 km cells wholly inside are one stored sum each; only cells along the edge are read at 100 m. The result equals a cell-by-cell count. With groups, the same steps read the age and sex pyramid and 100 m files instead, which carry population as well, so every group is counted over the same cells. With `years`, the part that does not depend on the year (which 10 km and 1 km cells are wholly inside, which 1 km cells the edge cuts) is worked out once, and each year's stored sums and edge are read, four years at a time.",
        "parameters": [
          {
            "$ref": "#/components/parameters/year"
          },
          {
            "$ref": "#/components/parameters/years"
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "r2025a",
              "pattern": "^r\\d{4}[a-z](/_test)?$"
            },
            "description": "The release; default r2025a. r2025a/_test is the two-country test set (Ethiopia and Kenya, age and sex for every year); age and sex for the default release cover 2015, 2020, 2025 and 2030."
          },
          {
            "$ref": "#/components/parameters/groups"
          },
          {
            "$ref": "#/components/parameters/indicators"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "GeoJSON Polygon, MultiPolygon, Feature or FeatureCollection, lon/lat (EPSG:4326)",
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Population inside",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "population": {
                      "type": "number"
                    },
                    "cells": {
                      "type": "integer",
                      "description": "valued 100 m cells inside"
                    },
                    "groups": {
                      "$ref": "#/components/schemas/Groups"
                    },
                    "group_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      },
                      "description": "What each asked-for sum adds up"
                    },
                    "method": {
                      "type": "object",
                      "properties": {
                        "rule": {
                          "type": "string"
                        },
                        "cells_10km": {
                          "type": "integer"
                        },
                        "cells_1km": {
                          "type": "integer"
                        },
                        "edge_cells_1km": {
                          "type": "integer"
                        },
                        "tiles_100m": {
                          "type": "integer",
                          "description": "100 m tiles read along the edge: 512 × 512 for population alone, 32 × 32 (43 bands) with groups"
                        },
                        "files_100m": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "reads": {
                          "type": "integer",
                          "description": "ranged reads of tile data, neighbouring tiles merged"
                        },
                        "bytes_read": {
                          "type": "integer",
                          "description": "compressed bytes those reads fetched"
                        }
                      }
                    },
                    "milliseconds": {
                      "type": "integer"
                    },
                    "source": {
                      "type": "string"
                    },
                    "years": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YearFigure"
                      },
                      "description": "With `years`: one entry per year"
                    },
                    "change": {
                      "$ref": "#/components/schemas/Change"
                    },
                    "peak": {
                      "$ref": "#/components/schemas/Peak"
                    },
                    "indicators": {
                      "$ref": "#/components/schemas/Indicators"
                    },
                    "indicator_definitions": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too large for one request: split it, or use /v1/worldpop/totals"
          },
          "429": {
            "description": "Over a rate limit: 2,000 API calls an hour per IP (wait Retry-After, until the hour ends), or this endpoint's per-minute limit (about a minute)",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/worldpop/catchment": {
      "get": {
        "operationId": "worldpopCatchment",
        "summary": "People within distances of a point",
        "description": "Each radius is a geodesic circle drawn as a polygon of 256 vertices (destination points on a sphere of radius 6,371,008.8 m), inscribed in the circle: it covers 99.99% of the circle's area. Each is then counted as a polygon (a 100 m cell counts when its centre is inside). `rings` count everyone within each radius; `bands` the people between one radius and the previous. Circles may not cross the antimeridian.",
        "parameters": [
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 36.8219
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": -1.2921
          },
          {
            "name": "radii",
            "in": "query",
            "required": true,
            "description": "1 to 10 distances in km, ascending, each above 0 and at most 100",
            "schema": {
              "type": "string"
            },
            "example": "1,5,10"
          },
          {
            "$ref": "#/components/parameters/year"
          },
          {
            "$ref": "#/components/parameters/years"
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "r2025a",
              "pattern": "^r\\d{4}[a-z](/_test)?$"
            },
            "description": "The release; default r2025a. r2025a/_test is the two-country test set (Ethiopia and Kenya, age and sex for every year); age and sex for the default release cover 2015, 2020, 2025 and 2030."
          },
          {
            "$ref": "#/components/parameters/groups"
          },
          {
            "$ref": "#/components/parameters/indicators"
          }
        ],
        "responses": {
          "200": {
            "description": "People within each radius and between them",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lon": {
                      "type": "number"
                    },
                    "lat": {
                      "type": "number"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "rings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "population": {
                            "type": "number"
                          },
                          "groups": {
                            "$ref": "#/components/schemas/Groups"
                          },
                          "indicators": {
                            "$ref": "#/components/schemas/Indicators"
                          },
                          "years": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/YearFigure"
                            }
                          },
                          "change": {
                            "$ref": "#/components/schemas/Change"
                          },
                          "peak": {
                            "$ref": "#/components/schemas/Peak"
                          },
                          "radius_km": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "bands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "population": {
                            "type": "number"
                          },
                          "groups": {
                            "$ref": "#/components/schemas/Groups"
                          },
                          "indicators": {
                            "$ref": "#/components/schemas/Indicators"
                          },
                          "years": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/YearFigure"
                            }
                          },
                          "change": {
                            "$ref": "#/components/schemas/Change"
                          },
                          "peak": {
                            "$ref": "#/components/schemas/Peak"
                          },
                          "from_km": {
                            "type": "number"
                          },
                          "to_km": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "method": {
                      "type": "object"
                    },
                    "milliseconds": {
                      "type": "integer"
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed: missing lon, lat or radii, more than 10 radii, a radius over 100 km, or a circle across the antimeridian",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published for that year (with years: missing_years)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too much edge to read in one request (radii times years)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/landscan-mosaic/point": {
      "get": {
        "operationId": "landscanMosaicPoint",
        "summary": "LandScan Mosaic: people in the 3 arc-second cell under a point",
        "parameters": [
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 38.7578
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 9.03
          },
          {
            "$ref": "#/components/parameters/mosaicYear"
          },
          {
            "$ref": "#/components/parameters/mosaicYears"
          },
          {
            "$ref": "#/components/parameters/mosaicRelease"
          }
        ],
        "responses": {
          "200": {
            "description": "population (and groups) are null where the cell has no value",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lon": {
                      "type": "number"
                    },
                    "lat": {
                      "type": "number"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "file": {
                      "type": "string"
                    },
                    "population": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "cell": {
                      "type": "object"
                    },
                    "source": {
                      "type": "string"
                    },
                    "years": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YearFigure"
                      },
                      "description": "With `years`: one entry per year"
                    },
                    "change": {
                      "$ref": "#/components/schemas/Change"
                    },
                    "peak": {
                      "$ref": "#/components/schemas/Peak"
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "description": "The cell of ORNL's global GeoTIFF for the year under the point. `population` is null where the cell has no value. The file covers 83.67° N to 56.54° S; outside it the answer is null with a note."
      }
    },
    "/v1/landscan-mosaic/polygon": {
      "post": {
        "operationId": "landscanMosaicPolygon",
        "summary": "LandScan Mosaic: people inside any polygon, exactly",
        "description": "A 3 arc-second cell (exactly 1/1200 degree, about 90 m at the equator) counts when its centre is inside the polygon (even-odd: holes and multipolygons work). Answered as for WorldPop: from a sum pyramid at 1/120 and 1/12 degree built from ORNL's file, and the 3 arc-second cells along the edge, read from ORNL's global GeoTIFF for the year. The result equals a cell-by-cell count of that file. LandScan Mosaic is ambient (24-hour average) population, not residents; see /llms.txt.",
        "parameters": [
          {
            "$ref": "#/components/parameters/mosaicYear"
          },
          {
            "$ref": "#/components/parameters/mosaicYears"
          },
          {
            "$ref": "#/components/parameters/mosaicRelease"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "GeoJSON Polygon, MultiPolygon, Feature or FeatureCollection, lon/lat (EPSG:4326)",
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Population inside",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "population": {
                      "type": "number"
                    },
                    "cells": {
                      "type": "integer",
                      "description": "valued 3 arc-second cells inside"
                    },
                    "method": {
                      "type": "object",
                      "properties": {
                        "rule": {
                          "type": "string"
                        },
                        "cells_10km": {
                          "type": "integer"
                        },
                        "cells_1km": {
                          "type": "integer"
                        },
                        "edge_cells_1km": {
                          "type": "integer"
                        },
                        "tiles_100m": {
                          "type": "integer",
                          "description": "100 m tiles read along the edge: 512 × 512 for population alone, 32 × 32 (43 bands) with groups"
                        },
                        "files_100m": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "reads": {
                          "type": "integer",
                          "description": "ranged reads of tile data, neighbouring tiles merged"
                        },
                        "bytes_read": {
                          "type": "integer",
                          "description": "compressed bytes those reads fetched"
                        }
                      }
                    },
                    "milliseconds": {
                      "type": "integer"
                    },
                    "source": {
                      "type": "string"
                    },
                    "years": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/YearFigure"
                      },
                      "description": "With `years`: one entry per year"
                    },
                    "change": {
                      "$ref": "#/components/schemas/Change"
                    },
                    "peak": {
                      "$ref": "#/components/schemas/Peak"
                    },
                    "change_definition": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published: report as missing, do not substitute another figure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too large for one request: split it, or use /v1/worldpop/totals"
          },
          "429": {
            "description": "Over a rate limit: 2,000 API calls an hour per IP (wait Retry-After, until the hour ends), or this endpoint's per-minute limit (about a minute)",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/landscan-mosaic/catchment": {
      "get": {
        "operationId": "landscanMosaicCatchment",
        "summary": "LandScan Mosaic: people within distances of a point",
        "description": "Each radius is a geodesic circle drawn as a polygon of 256 vertices (destination points on a sphere of radius 6,371,008.8 m), inscribed in the circle: it covers 99.99% of the circle's area. Each is then counted as a polygon (a 3 arc-second cell (exactly 1/1200 degree, about 90 m at the equator) counts when its centre is inside). `rings` count everyone within each radius; `bands` the people between one radius and the previous.",
        "parameters": [
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": 36.8219
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "example": -1.2921
          },
          {
            "name": "radii",
            "in": "query",
            "required": true,
            "description": "1 to 10 distances in km, ascending, each above 0 and at most 100",
            "schema": {
              "type": "string"
            },
            "example": "1,5,10"
          },
          {
            "$ref": "#/components/parameters/mosaicYear"
          },
          {
            "$ref": "#/components/parameters/mosaicYears"
          },
          {
            "$ref": "#/components/parameters/mosaicRelease"
          }
        ],
        "responses": {
          "200": {
            "description": "People within each radius and between them",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "lon": {
                      "type": "number"
                    },
                    "lat": {
                      "type": "number"
                    },
                    "year": {
                      "type": "integer"
                    },
                    "release": {
                      "type": "string"
                    },
                    "rings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "population": {
                            "type": "number"
                          },
                          "years": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/YearFigure"
                            }
                          },
                          "change": {
                            "$ref": "#/components/schemas/Change"
                          },
                          "peak": {
                            "$ref": "#/components/schemas/Peak"
                          },
                          "radius_km": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "bands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "population": {
                            "type": "number"
                          },
                          "years": {
                            "type": "array",
                            "items": {
                              "$ref": "#/components/schemas/YearFigure"
                            }
                          },
                          "change": {
                            "$ref": "#/components/schemas/Change"
                          },
                          "peak": {
                            "$ref": "#/components/schemas/Peak"
                          },
                          "from_km": {
                            "type": "number"
                          },
                          "to_km": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "method": {
                      "type": "object"
                    },
                    "milliseconds": {
                      "type": "integer"
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Malformed: missing lon, lat or radii, more than 10 radii, a radius over 100 km, or a circle across the antimeridian",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not published for that year (with years: missing_years)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too much edge to read in one request (radii times years)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 2,000 API calls this hour from this IP; wait Retry-After seconds",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Limit": {
                "description": "API calls allowed per IP per clock hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left this hour",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "When the hour ends, epoch seconds",
                "schema": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "/v1/vnl/polygon": {
      "post": {
        "operationId": "vnlPolygon",
        "summary": "Night lights (EOG VNL) inside any polygon, exactly",
        "description": "A 15 arc-second VNL cell counts when its centre is inside the polygon (even-odd). Answered from VNL sum pyramids (2 and 20 cells to a side) and the 15 arc-second cells along the edge; the population-weighted figures from a joint WorldPop x VNL pyramid on WorldPop's 1 km and 10 km grid and WorldPop's 100 m cells along the edge, each taking the VNL cell under its centre (a centre on a VNL edge goes east and south). Equals a cell-by-cell count. Pass on `notice` with any figure: EOG's licence asks for it on graphs and pictures, and its logo on large-format graphics. Every year 2012-2025; each year is read from its own EOG version, V2.1 (2012-2021) or V2.2 (2022 onwards).",
        "parameters": [
          {
            "$ref": "#/components/parameters/vnlYear"
          },
          {
            "$ref": "#/components/parameters/vnlYears"
          },
          {
            "$ref": "#/components/parameters/vnlRelease"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "GeoJSON Polygon, MultiPolygon, Feature or FeatureCollection, lon/lat (EPSG:4326)",
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Night lights inside",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "mean_radiance": {
                      "type": "number",
                      "nullable": true,
                      "description": "area-weighted mean radiance, nW/cm2/sr"
                    },
                    "sum_of_lights": {
                      "type": "number",
                      "description": "radiance x cell area, nW/sr"
                    },
                    "sum_of_values": {
                      "type": "number",
                      "description": "radiance summed over cells, unweighted"
                    },
                    "lit_share": {
                      "type": "number",
                      "nullable": true,
                      "description": "share of the area in cells with radiance != 0 (EOG's mask)"
                    },
                    "area_km2": {
                      "type": "number"
                    },
                    "cells": {
                      "type": "integer"
                    },
                    "lit_cells": {
                      "type": "integer"
                    },
                    "population": {
                      "type": "object",
                      "nullable": true,
                      "description": "null for years WorldPop does not have",
                      "properties": {
                        "weighted_mean_radiance": {
                          "type": "number",
                          "nullable": true
                        },
                        "unlit_share": {
                          "type": "number",
                          "nullable": true
                        },
                        "people": {
                          "type": "number"
                        },
                        "people_with_light_value": {
                          "type": "number"
                        },
                        "cells_100m": {
                          "type": "integer"
                        },
                        "worldpop_release": {
                          "type": "string"
                        }
                      }
                    },
                    "units": {
                      "type": "object"
                    },
                    "definitions": {
                      "type": "object"
                    },
                    "method": {
                      "type": "object"
                    },
                    "milliseconds": {
                      "type": "integer"
                    },
                    "notice": {
                      "type": "string"
                    },
                    "licence_note": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad parameters or body"
          },
          "404": {
            "description": "Not published for that year and release"
          },
          "413": {
            "description": "Too large: split the polygon or ask for fewer years"
          }
        }
      }
    },
    "/v1/chirps/polygon": {
      "post": {
        "operationId": "chirpsPolygon",
        "summary": "CHIRPS rainfall inside any polygon, per month, against the 1991-2020 normal",
        "description": "Rainfall is a depth, so the figure is a mean, weighted by area. A 100 m cell (exactly 1/1200 degree) counts when its centre is inside the polygon (even-odd) and takes the rainfall of the 0.05 degree CHIRPS cell containing it: each CHIRPS cell is exactly 60 x 60 of them, edge on edge, so nothing is resampled. The mean is weighted by the spherical area of the counted 100 m cells, over the cells where both the month and the normal have a value. Equals a GDAL cell-by-cell count (test/chirps.check.ts). The normal is computed by data-geo, not by the Climate Hazards Center. Rainfall only: no population; join with a population endpoint yourself if you need it.",
        "parameters": [
          {
            "$ref": "#/components/parameters/chirpsMonth"
          },
          {
            "$ref": "#/components/parameters/chirpsMonths"
          },
          {
            "$ref": "#/components/parameters/chirpsRelease"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "GeoJSON Polygon, MultiPolygon, Feature or FeatureCollection, lon/lat (EPSG:4326)",
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One month: its figures at the top level. Several: `months` and `total`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ChirpsMonth"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "months": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ChirpsMonth"
                          }
                        },
                        "total": {
                          "type": "object",
                          "description": "several months: sums of the monthly rainfall_mm and normal_mm, anomaly and percent from those sums",
                          "properties": {
                            "months": {
                              "type": "integer"
                            },
                            "rainfall_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "normal_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "anomaly_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "percent_of_normal": {
                              "type": "number",
                              "nullable": true
                            }
                          }
                        },
                        "area_inside_km2": {
                          "type": "number"
                        },
                        "method": {
                          "type": "object"
                        },
                        "milliseconds": {
                          "type": "integer"
                        },
                        "units": {
                          "type": "object"
                        },
                        "definitions": {
                          "type": "object"
                        },
                        "normal": {
                          "type": "string"
                        },
                        "normal_note": {
                          "type": "string"
                        },
                        "release": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad parameters or body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "A month not published yet (`missing_months`, `last_month`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too large: the box spans over 2,000,000 CHIRPS cells, or months x tiles over the request's budget",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/chirps/point": {
      "get": {
        "operationId": "chirpsPoint",
        "summary": "CHIRPS rainfall in the 0.05 degree cell under a point, per month, with the normal",
        "parameters": [
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            }
          },
          {
            "$ref": "#/components/parameters/chirpsMonth"
          },
          {
            "$ref": "#/components/parameters/chirpsMonths"
          },
          {
            "$ref": "#/components/parameters/chirpsRelease"
          }
        ],
        "responses": {
          "200": {
            "description": "The cell's figures",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ChirpsMonth"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "lon": {
                          "type": "number"
                        },
                        "lat": {
                          "type": "number"
                        },
                        "cell": {
                          "type": "object"
                        },
                        "months": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ChirpsMonth"
                          }
                        },
                        "total": {
                          "type": "object",
                          "description": "several months: sums of the monthly rainfall_mm and normal_mm, anomaly and percent from those sums",
                          "properties": {
                            "months": {
                              "type": "integer"
                            },
                            "rainfall_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "normal_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "anomaly_mm": {
                              "type": "number",
                              "nullable": true
                            },
                            "percent_of_normal": {
                              "type": "number",
                              "nullable": true
                            }
                          }
                        },
                        "rule": {
                          "type": "string"
                        },
                        "units": {
                          "type": "object"
                        },
                        "definitions": {
                          "type": "object"
                        },
                        "normal": {
                          "type": "string"
                        },
                        "normal_note": {
                          "type": "string"
                        },
                        "release": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad parameters"
          },
          "404": {
            "description": "Outside 60 N-60 S, or a month not published"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/v1/vnl/monthly/polygon": {
      "post": {
        "operationId": "vnlMonthlyPolygon",
        "summary": "Monthly night lights (EOG VNL monthly) inside any polygon, exactly",
        "description": "A 15 arc-second cell counts when its centre is inside the polygon (even-odd). Answered from a 10 km sum pyramid and the 15 arc-second cells elsewhere, read from radiance.tif (EOG's avg_rade9h with no-cloud-free-night cells as nodata). No background mask, no lit share, no population join. Pass on `notice` with any figure. In testing: release v10/_test, months as they are built.",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$"
            },
            "description": "The month, YYYY-MM, 2012-04 to 2026-09. Give month or months."
          },
          {
            "name": "months",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "In place of month: a comma list of months and ranges, e.g. 2024-01/2024-12,2025-06. The answer lists each month."
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^v10(/_test)?$",
              "default": "v10"
            },
            "description": "EOG's monthly version, v10. In testing: v10/_test."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "description": "GeoJSON Polygon, MultiPolygon, Feature or FeatureCollection, lon/lat (EPSG:4326)",
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Monthly night lights inside",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "mean_radiance": {
                      "type": "number",
                      "nullable": true,
                      "description": "area-weighted mean radiance over observed cells, nW/cm2/sr"
                    },
                    "sum_of_lights": {
                      "type": "number",
                      "description": "radiance x cell area over observed cells, nW/sr"
                    },
                    "sum_of_values": {
                      "type": "number"
                    },
                    "observed_share": {
                      "type": "number",
                      "nullable": true,
                      "description": "share of the area with a cloud-free night that month"
                    },
                    "observed_area_km2": {
                      "type": "number"
                    },
                    "area_km2": {
                      "type": "number"
                    },
                    "cells": {
                      "type": "integer"
                    },
                    "notice": {
                      "type": "string"
                    },
                    "method": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad parameters or body"
          },
          "404": {
            "description": "Not published for that year and release"
          },
          "413": {
            "description": "Too large: split the polygon or ask for fewer years"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Groups": {
        "type": "object",
        "description": "People per asked-for group, by name",
        "additionalProperties": {
          "type": "number"
        },
        "example": {
          "female": 89.64,
          "male": 83.53,
          "under5": 13.39,
          "under18": 48.79,
          "women_15_49": 59.18,
          "age_15_64": 130.16,
          "age_65_plus": 5.87
        }
      },
      "Indicators": {
        "type": "object",
        "description": "Ratios per 100 (2 decimals), shares 0–1 (4 decimals), null where the denominator is 0. Shares are of everyone with age and sex data (the 40 groups).",
        "properties": {
          "median_age": {
            "type": [
              "number",
              "null"
            ],
            "description": "years; linear interpolation inside the five-year group holding the half-way person, 90 and over taken as 90–100"
          },
          "sex_ratio": {
            "type": [
              "number",
              "null"
            ],
            "description": "males per 100 females"
          },
          "dependency_ratio": {
            "type": "object",
            "properties": {
              "total": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "young": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "old": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "description": "0–14 (young), 65+ (old) and both (total) per 100 aged 15–64"
          },
          "aging_index": {
            "type": [
              "number",
              "null"
            ],
            "description": "65+ per 100 aged 0–14"
          },
          "child_woman_ratio": {
            "type": [
              "number",
              "null"
            ],
            "description": "children 0–4 per 100 women 15–49"
          },
          "shares": {
            "type": "object",
            "properties": {
              "under_5": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "under_15": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "under_18": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "age_15_64": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "age_65_plus": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "women_15_49": {
                "type": [
                  "number",
                  "null"
                ]
              }
            },
            "description": "under_18 is WorldPop's own under-18 count, null where unknown"
          }
        }
      },
      "Change": {
        "type": "object",
        "description": "From the first to the last year asked. With groups, `groups` holds the same per group.",
        "properties": {
          "from_year": {
            "type": "integer"
          },
          "to_year": {
            "type": "integer"
          },
          "absolute": {
            "type": [
              "number",
              "null"
            ]
          },
          "percent": {
            "type": [
              "number",
              "null"
            ]
          },
          "annual_growth_percent": {
            "type": [
              "number",
              "null"
            ],
            "description": "compound annual growth rate, percent a year"
          },
          "groups": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "Peak": {
        "type": "object",
        "description": "The year with the most people (the first, on a tie); with groups, `groups` holds {year, value} per group.",
        "properties": {
          "year": {
            "type": "integer"
          },
          "population": {
            "type": "number"
          },
          "groups": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "YearFigure": {
        "type": "object",
        "description": "One year of a `years` answer: the fields a single-year answer has for that year.",
        "properties": {
          "year": {
            "type": "integer"
          },
          "population": {
            "type": [
              "number",
              "null"
            ]
          },
          "groups": {
            "$ref": "#/components/schemas/Groups"
          },
          "indicators": {
            "$ref": "#/components/schemas/Indicators"
          }
        },
        "additionalProperties": true
      },
      "ChirpsMonth": {
        "type": "object",
        "properties": {
          "month": {
            "type": "string"
          },
          "rainfall_mm": {
            "type": "number",
            "nullable": true,
            "description": "area-weighted mean rainfall total of the month, mm"
          },
          "normal_mm": {
            "type": "number",
            "nullable": true,
            "description": "data-geo's 1991-2020 normal for that calendar month, over the same cells, mm (not a CHC product)"
          },
          "anomaly_mm": {
            "type": "number",
            "nullable": true,
            "description": "rainfall_mm - normal_mm"
          },
          "percent_of_normal": {
            "type": "number",
            "nullable": true,
            "description": "100 x rainfall_mm / normal_mm"
          },
          "area_km2": {
            "type": "number",
            "description": "area with a value in the month and the normal (polygon only)"
          },
          "area_no_value_km2": {
            "type": "number",
            "description": "area inside without a value: sea, outside 60 N-60 S (polygon only)"
          }
        }
      }
    },
    "parameters": {
      "groups": {
        "name": "groups",
        "in": "query",
        "required": false,
        "description": "Break the answer down by sex and age. `all`: the 42 stored bands. `summary`: female, male, under5, under18, women_15_49, age_15_64, age_65_plus. Or a comma list of any of: the bands f_00, f_01, f_05, f_10, … f_90 and m_00 … m_90 (sex; age group 00 = under 1, 01 = 1–4, 05 = 5–9, …, 90 = 90 and over), f_under18, m_under18 (WorldPop's own under-18 counts); and the sums female, male, under1, under5, under15, under18, age_15_64, age_65_plus, women_15_49, t_00 … t_90 (both sexes). Every figure is counted over the same cells by the same rule as population, so they add up with each other; the 40 sex-by-age bands sum to population within 3.1e-5 of a person per 100 m cell. Under-18 figures are null for any area including Russia, Fiji or Greenland, for which WorldPop publishes none.",
        "schema": {
          "type": "string"
        },
        "example": "summary"
      },
      "years": {
        "name": "years",
        "in": "query",
        "required": false,
        "description": "Several years in place of `year` (give one, not both): a comma list and ranges, e.g. `2015,2020,2025` or `2015-2030`, each 2015–2030, at most 16. The answer then lists each year under `years`, in ascending order, and with two or more adds `change` (first to last year) and `peak`, for population and for each group asked. With `groups` or `indicators`, every year asked must have age and sex data (2015, 2020, 2025, 2030), or the answer is 404 with `missing_years`. A polygon or catchment over several years is limited by its edge times the years (413 with a hint).",
        "schema": {
          "type": "string"
        },
        "example": "2015-2030"
      },
      "indicators": {
        "name": "indicators",
        "in": "query",
        "required": false,
        "description": "`true` adds `indicators` (median age, sex ratio, dependency ratios, ageing index, child-woman ratio, age shares) and `indicator_definitions`, computed from the 42 age and sex sums of the same cells. Names and definitions as WorldPop's API v3 POST /indicators. Years with age and sex data only.",
        "schema": {
          "type": "boolean",
          "default": false
        }
      },
      "year": {
        "name": "year",
        "in": "query",
        "required": false,
        "description": "One year, 2015–2030. Give `year` or `years`.",
        "schema": {
          "type": "integer",
          "minimum": 2015,
          "maximum": 2030
        },
        "example": 2025
      },
      "mosaicYear": {
        "name": "year",
        "in": "query",
        "required": false,
        "description": "One year, 1975–2024 (LandScan Mosaic Time Series). Give `year` or `years`. A year not yet published answers 404; `/v1/catalog` and `/v1` say which are.",
        "schema": {
          "type": "integer",
          "minimum": 1975,
          "maximum": 2024
        },
        "example": 2024
      },
      "mosaicYears": {
        "name": "years",
        "in": "query",
        "required": false,
        "description": "Several years in place of `year`: a comma list and ranges, e.g. `1975,2000,2024` or `2020-2024`, each 1975–2024. The answer lists each year under `years`, and with two or more adds `change` (first to last year) and `peak`. Every year asked must be published, or the answer is 404 with `missing_years`. A polygon or catchment over several years is limited by its edge times the years (413 with a hint).",
        "schema": {
          "type": "string"
        },
        "example": "2020-2024"
      },
      "mosaicRelease": {
        "name": "release",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "v1",
          "pattern": "^v1(/_test)?$"
        },
        "description": "The release; default v1. v1/_test is the test set (1975 and 2024)."
      },
      "vnlYear": {
        "name": "year",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 2012,
          "maximum": 2025
        },
        "description": "The year, 2012-2025 (2012 is April to December). Give year or years."
      },
      "vnlYears": {
        "name": "years",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "In place of year: a comma list and ranges, e.g. 2022-2024. The answer lists each year."
      },
      "vnlRelease": {
        "name": "release",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^(test|v2[12](/_test)?)$"
        },
        "description": "Left out (normal), each year is read from its own EOG version: v21 (V2.1) for 2012-2021, v22 (V2.2) from 2022. Or the year's own version by name: v21, v22. test, v21/_test, v22/_test: the files from testing."
      },
      "chirpsMonth": {
        "name": "month",
        "in": "query",
        "required": false,
        "description": "One month, YYYY-MM, 1981-01 onwards (to the newest month the CHC has posted, see /chirps/latest.json). Give month or months.",
        "schema": {
          "type": "string",
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
        },
        "example": "2026-09"
      },
      "chirpsMonths": {
        "name": "months",
        "in": "query",
        "required": false,
        "description": "Several months: FIRST..LAST (e.g. 2026-07..2026-09) or a comma list, at most 120. The answer lists each month and `total`.",
        "schema": {
          "type": "string"
        },
        "example": "2026-07..2026-09"
      },
      "chirpsRelease": {
        "name": "release",
        "in": "query",
        "required": false,
        "description": "Left out: the published normals. `_test`: the normals under test.",
        "schema": {
          "type": "string",
          "enum": [
            "v3.0",
            "_test"
          ]
        }
      }
    }
  }
}