Geographic Distribution Service - API Contract

GET /api/v1/geographic-distributions/api/v1/geographic-distributions

List geographic distribution summaries for org/period combinations

Public

Response Example

{
  "data": [
    {
      "id": "geodist-07",
      "org_id": "org-bufdir-42",
      "period_id": "rp-2024-q4",
      "breakdown_type": "region",
      "region_count": 5,
      "top_region": "Viken",
      "generated_at": "2025-01-05T08:10:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 4
  }
}

GET /api/v1/geographic-distributions/api/v1/geographic-distributions/:id

Get a specific geographic distribution record

Public

Response Example

{
  "id": "geodist-07",
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "breakdown_type": "region",
  "distribution": [
    {
      "region": "Viken",
      "participant_count": 540,
      "activity_count": 82
    },
    {
      "region": "Oslo",
      "participant_count": 420,
      "activity_count": 65
    },
    {
      "region": "Innlandet",
      "participant_count": 310,
      "activity_count": 48
    }
  ],
  "generated_at": "2025-01-05T08:10:00Z"
}

POST /api/v1/geographic-distributions/api/v1/geographic-distributions

Generate a geographic distribution breakdown for an org and period

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "breakdown_type": "local_chapter"
}

Response Example

{
  "id": "geodist-15",
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "breakdown_type": "local_chapter",
  "distribution": [
    {
      "local_chapter_id": "lc-oslo-nord",
      "local_chapter_name": "Oslo Nord",
      "participant_count": 198,
      "activity_count": 31
    },
    {
      "local_chapter_id": "lc-bergen",
      "local_chapter_name": "Bergen",
      "participant_count": 145,
      "activity_count": 22
    }
  ],
  "generated_at": "2025-03-26T09:05:00Z"
}

PUT /api/v1/geographic-distributions/api/v1/geographic-distributions/:id

Refresh an existing geographic distribution record

Public

Request Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "force_refresh": true
}

Response Example

{
  "id": "geodist-15",
  "org_id": "org-bufdir-42",
  "period_id": "rp-2025-q1",
  "breakdown_type": "local_chapter",
  "distribution": [
    {
      "local_chapter_id": "lc-oslo-nord",
      "local_chapter_name": "Oslo Nord",
      "participant_count": 204,
      "activity_count": 33
    }
  ],
  "generated_at": "2025-03-26T09:30:00Z"
}

DELETE /api/v1/geographic-distributions/api/v1/geographic-distributions/:id

Delete a geographic distribution record

Public

Response Example

{
  "deleted": true,
  "id": "geodist-07"
}

GET /api/v1/geographic-distributions/api/v1/geographic-distributions/by-region

Get participant distribution broken down by region for an org/period

Public

Response Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "breakdown": [
    {
      "region": "Viken",
      "participant_count": 540,
      "percentage": 29.3
    },
    {
      "region": "Oslo",
      "participant_count": 420,
      "percentage": 22.8
    }
  ]
}

GET /api/v1/geographic-distributions/api/v1/geographic-distributions/by-local-chapter

Get participant distribution broken down by local chapter

Public

Response Example

{
  "org_id": "org-bufdir-42",
  "period_id": "rp-2024-q4",
  "breakdown": [
    {
      "local_chapter_id": "lc-oslo-nord",
      "local_chapter_name": "Oslo Nord",
      "participant_count": 198,
      "percentage": 10.7
    },
    {
      "local_chapter_id": "lc-bergen",
      "local_chapter_name": "Bergen",
      "participant_count": 145,
      "percentage": 7.9
    }
  ]
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}