Merge pull request #80 from Ensembl/genome-counts

add genome_counts endpoint

Author: bilalebi

app/api/models/genome.py

@@ -207,4 +207,14 @@ class GenomeGroupsResponse(BaseModel):
     genome_groups: list[GenomeGroup] = Field(alias="genomeGroups")
 
 class GenomesInGroupResponse(BaseModel):
-    genomes: list[BaseGenomeDetails] = Field(alias="genomes")
+    genomes: list[BaseGenomeDetails] = Field(alias="genomes")
+
+
+class GenomeCountItem(BaseModel):
+    label: str
+    count: int
+
+
+class GenomeCountsResponse(BaseModel):
+    total: int = 0
+    counts: list[GenomeCountItem] = Field(default_factory=list)

app/api/resources/grpc_client.py

@@ -182,4 +182,11 @@ def get_genomes_in_group(self, group_id: str, release_label: str):
             "ensembl_metadata.GenomesInGroupRequest"
         )
         request = request_class(group_id=group_id, release_label=release_label)
-        return self.stub.GetGenomesInGroup(request)
+        return self.stub.GetGenomesInGroup(request)
+
+    def get_genome_counts(self, release_label: str | None):
+        request_class = self.reflector.message_class(
+            "ensembl_metadata.GenomeCountsRequest"
+        )
+        request = request_class(release_label=release_label)
+        return self.stub.GetGenomeCounts(request)

app/api/resources/metadata.py

@@ -26,7 +26,7 @@
 from api.models.popular_species import PopularSpeciesGroup
 from api.models.karyotype import Karyotype
 from api.models.genome import BriefGenomeDetails, GenomeDetails, DatasetAttributes, GenomeByKeyword, Release, \
-    GenomeGroupsResponse, GenomesInGroupResponse
+    GenomeGroupsResponse, GenomesInGroupResponse, GenomeCountsResponse
 from api.models.ftplinks import FTPLinks
 from api.models.vep import VepFilePaths
 
@@ -350,16 +350,16 @@ async def get_releases(
     return response_data
 
 @router.get("/genome_groups", name="genome_groups")
-@redis_cache("genome_groups", arg_keys=["group_type", "release_label"])
+@redis_cache("genome_groups", arg_keys=["group_type", "release"])
 async def get_genome_groups(
         group_type: str = Query(..., description="Group type, e.g. 'structural_variant'"),
-        release_label: str | None = Query(None, description="Optional release label, e.g. '2025-02'")
+        release: str | None = Query(None, description="Optional release label, e.g. '2025-02'")
 ):
     try:
         genome_groups_dict = MessageToDict(
             grpc_client.get_genome_groups_with_reference(
                 group_type=group_type,
-                release_label=release_label
+                release_label=release
             )
         )
         logging.debug(f"genome_groups_dict: {genome_groups_dict}")
@@ -377,16 +377,16 @@ async def get_genome_groups(
         return response_error_handler({"status": 500})
 
 @router.get("/genome_groups/{group_id}/genomes", name="genomes_in_group")
-@redis_cache("genomes_in_group", arg_keys=["group_id", "release_label"])
+@redis_cache("genomes_in_group", arg_keys=["group_id", "release"])
 async def get_genomes_in_group(
         group_id: str = Path(..., description="Group ID, e.g. 'grch38-group'"),
-        release_label: str | None = Query(None, description="Optional release label, e.g. '2025-02'")
+        release: str | None = Query(None, description="Optional release label, e.g. '2025-02'")
 ):
     try:
         genomes_in_group_dict = MessageToDict(
             grpc_client.get_genomes_in_group(
                 group_id=group_id,
-                release_label=release_label
+                release_label=release
             )
         )
         logging.debug(f"genomes_in_group_dict: {genomes_in_group_dict}")
@@ -402,3 +402,20 @@ async def get_genomes_in_group(
     except Exception as ex:
         logging.exception("Error in get_genomes_in_group")
         return response_error_handler({"status": 500})
+
+
+@router.get("/genome_counts", name="genome_counts")
+@redis_cache(key_prefix="genome_counts", arg_keys=["release"])
+async def get_genome_counts(
+    release: str | None = Query(None, description="Optional release label to filter counts, e.g. '2025-02'")
+):
+    try:
+        genome_counts_dict = MessageToDict(
+            grpc_client.get_genome_counts(release_label=release)
+        )
+        genome_counts = GenomeCountsResponse(**genome_counts_dict)
+        response_data = responses.JSONResponse(genome_counts.model_dump(), status_code=200)
+    except Exception as ex:
+        logging.exception("Error in get_genome_counts")
+        return response_error_handler({"status": 500})
+    return response_data

docs/APISpecification.yaml

@@ -235,6 +235,29 @@ paths:
                       $ref: '#/components/schemas/PopularSpecies'
         '500':
           $ref: '#/components/responses/500InternalServerError'
+  /api/metadata/genome_counts:
+    get:
+      tags:
+        - api
+      summary: Genome counts grouped by specific taxonomic group
+      description: Returns aggregated genome counts optionally filtered by release label.
+      parameters:
+        - name: release
+          in: query
+          required: false
+          description: Filter counts for genomes that belong to a specific release label.
+          schema:
+            type: string
+            example: 2025-05
+      responses:
+        '200':
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GenomeCountsResponse'
+        '500':
+          $ref: '#/components/responses/500InternalServerError'
   /api/metadata/genome/{genome_id}/dataset/{dataset_type}/attributes:
     get:
       description: Returns a list of attributes of a given dataset of a genome.
@@ -392,7 +415,7 @@ paths:
             schema:
               type: string
           - in: query
-            name: release_label
+            name: release
             required: false
             schema:
               type: string
@@ -420,7 +443,7 @@ paths:
           schema:
             type: string
         - in: query
-          name: release_label
+          name: release
           required: false
           schema:
             type: string
@@ -508,6 +531,31 @@ components:
         - type
         - is_reference
         - latest_genome
+    GenomeCountItem:
+      type: object
+      properties:
+        label:
+          type: string
+          example: Animals
+        count:
+          type: integer
+          example: 1207
+      required:
+        - label
+        - count
+    GenomeCountsResponse:
+      type: object
+      properties:
+        total:
+          type: integer
+          example: 4218
+        counts:
+          type: array
+          items:
+            $ref: '#/components/schemas/GenomeCountItem'
+      required:
+        - total
+        - counts
     GenomeStats:
       type: object
       properties: