update the projects endpoints to return bbox in the payload

[andersy005]

This PR updates the project endpoints to return bbox in the payload by:

• loading bbox data from s3://carbonplan-offsets-db/miscellaneous/project-boundaries.parquet
• caching this data in memory (to avoid repeated S3 reads). the data are loaded from S3 on first request and cached for subsequent requests
• provides helper functions for single and batch lookups

now GET /projects/ includes bbox for each in the paginated resutls
and GET /projects/{project_id} includes bbox for the single project.

for example: GET https://offsets-db-staging.fly.dev/projects/VCS1000 returns

{
  "project_id": "VCS1000",
  "name": "Conversion to Proteccion of the Amazon Rain Forest",
  "registry": "verra",
  "proponent": "Multiple Proponents",
  "protocol": [
    "vm0010"
  ],
  "category": "forest",
  "status": "listed",
  "country": "Bolivia",
  "listed_at": null,
  "is_compliance": false,
  "retired": 0,
  "issued": 0,
  "first_issuance_at": null,
  "first_retirement_at": null,
  "project_url": "https://registry.verra.org/app/projectDetail/VCS/1000",
  "project_type": "Improved Forest Management",
  "project_type_source": "berkeley",
  "clips": [],
  "bbox": {
    "xmin": -66.951948,
    "ymin": -11.101475,
    "xmax": -66.870606,
    "ymax": -11.02284
  }
}

[katamartin]

This looks great to me, as long as we feel good about how the performance will scale. Is the plan to quietly roll this out to production and observe?

One tiny nit: it seems like the /projects/ and /projects/{project_id} endpoints have will return slightly different things for projects w/o boundaries? The former will omit the bbox key, where the latter will include bbox: null -- is that right? If so, could we make them identical (either is fine!)?

[andersy005]

One tiny nit: it seems like the /projects/ and /projects/{project_id} endpoints have will return slightly different things for projects w/o boundaries? The former will omit the bbox key, where the latter will include bbox: null -- is that right? If so, could we make them identical (either is fine!)?

both /projects/ and /projects/{project_id} endpoints return bbox: null

{
  "project_id": "ACR1001",
  "name": "Whirlpool HFO Supsa 1001",
  "registry": "american-carbon-registry",
  "proponent": null,
  "protocol": [
    "acr-foam"
  ],
  "category": "ghg-management",
  "status": "completed",
  "country": "Mexico",
  "listed_at": null,
  "is_compliance": false,
  "retired": 0,
  "issued": 1568319,
  "first_issuance_at": "2025-05-27",
  "first_retirement_at": null,
  "project_url": "https://acr2.apx.com/mymodule/reg/prjView.asp?id1=1001",
  "project_type": "HFC Replacement",
  "project_type_source": "berkeley",
  "clips": [],
  "bbox": null
}

{
  "pagination": {
    "total_entries": 27,
    "current_page": 1,
    "total_pages": 14,
    "next_page": "http://offsets-db-staging.fly.dev/projects/?current_page=2&per_page=2&sort=project_id&registry=art-trees&beneficiary_search_fields=retirement_beneficiary_harmonized"
  },
  "data": [
    {
      "project_id": "ART101",
      "name": "Costa Rica",
      "registry": "art-trees",
      "proponent": "Fondo Nacional de Financiamento Forestal (FONAFIFO)",
      "protocol": [
        "art-trees"
      ],
      "category": "forest",
      "status": "listed",
      "country": "Costa Rica",
      "listed_at": null,
      "is_compliance": false,
      "retired": 0,
      "issued": 0,
      "first_issuance_at": null,
      "first_retirement_at": null,
      "project_url": "https://art.apx.com/mymodule/reg/prjView.asp?id1=101",
      "project_type": "REDD+",
      "project_type_source": "carbonplan",
      "clips": [],
      "bbox": null
    },
    {
      "project_id": "ART102",
      "name": "Guyana",
      "registry": "art-trees",
      "proponent": "Guyana Forestry Commission",
      "protocol": [
        "art-trees"
      ],
      "category": "forest",
      "status": "registered",
      "country": "Guyana",
      "listed_at": null,
      "is_compliance": false,
      "retired": 101408,
      "issued": 49347890,
      "first_issuance_at": "2022-12-01",
      "first_retirement_at": "2023-06-27",
      "project_url": "https://art.apx.com/mymodule/reg/prjView.asp?id1=102",
      "project_type": "REDD+",
      "project_type_source": "carbonplan",
      "clips": [],
      "bbox": null
    }
  ]
}

[andersy005]

Is the plan to quietly roll this out to production and observe?

this implementation looks good enough. 👍🏽 for rolling this out to prod and observing how it goes

[katamartin]

@Shane98c since you tested this, are you up for confirming this is good to go to production?

[Shane98c]

working well on staging for me!