✨ Add impression share reports API support

- Add custom_reports resource for impression share data
- Add ImpressionShareReport, ImpressionShareReportRow models
- Add ImpressionShareDateRange, ImpressionShareReportStatus enums
- Create/get/list/delete impression share reports
- Poll for async report completion with wait_for_report()
- Convenience method get_impression_share() handles full workflow

Author: SamPetherbridge

asa_api_client/client.py

@@ -13,6 +13,7 @@
 from asa_api_client.auth import Authenticator
 from asa_api_client.logging import get_logger
 from asa_api_client.resources.campaigns import CampaignResource
+from asa_api_client.resources.custom_reports import CustomReportResource
 from asa_api_client.resources.reports import ReportResource
 
 logger = get_logger(__name__)
@@ -34,6 +35,7 @@ class AppleSearchAdsClient:
         org_id: The Apple Search Ads organization ID.
         campaigns: Resource for managing campaigns.
         reports: Resource for generating reports.
+        custom_reports: Resource for impression share reports.
 
     Example:
         Basic usage::
@@ -134,6 +136,7 @@ def __init__(
         # Initialize resources
         self._campaigns = CampaignResource(self)
         self._reports = ReportResource(self)
+        self._custom_reports = CustomReportResource(self)
 
         logger.info(
             "AppleSearchAdsClient initialized for org_id=%d, base_url=%s",
@@ -261,6 +264,29 @@ def reports(self) -> ReportResource:
         """
         return self._reports
 
+    @property
+    def custom_reports(self) -> CustomReportResource:
+        """Get the custom reports resource for impression share data.
+
+        Returns:
+            CustomReportResource for generating impression share reports.
+
+        Example:
+            Get impression share report::
+
+                from datetime import date, timedelta
+
+                report = client.custom_reports.get_impression_share(
+                    start_date=date.today() - timedelta(days=7),
+                    end_date=date.today() - timedelta(days=1),
+                )
+
+                for row in report.row:
+                    share = f"{row.low_impression_share}-{row.high_impression_share}%"
+                    print(f"{row.metadata.keyword}: {share}")
+        """
+        return self._custom_reports
+
     def close(self) -> None:
         """Close the HTTP clients and release resources.
 

asa_api_client/models/__init__.py

@@ -52,6 +52,11 @@
 )
 from asa_api_client.models.reports import (
     GranularityType,
+    ImpressionShareDateRange,
+    ImpressionShareReport,
+    ImpressionShareReportRequest,
+    ImpressionShareReportRow,
+    ImpressionShareReportStatus,
     ReportingRequest,
     ReportingResponse,
     ReportMetadata,
@@ -83,6 +88,11 @@
     "ConditionOperator",
     "CpaGoal",
     "GranularityType",
+    "ImpressionShareDateRange",
+    "ImpressionShareReport",
+    "ImpressionShareReportRequest",
+    "ImpressionShareReportRow",
+    "ImpressionShareReportStatus",
     "Keyword",
     "KeywordCreate",
     "KeywordMatchType",

asa_api_client/models/reports.py

@@ -340,12 +340,17 @@ class ImpressionShareReportRow(BaseModel):
     """A row in an impression share report.
 
     Impression share shows how often your ads appeared compared
-    to the total available impressions.
+    to the total available impressions. Values are percentage ranges.
 
     Attributes:
-        metadata: Information about the entity.
-        impression_share: Your share of impressions (0.0 to 1.0).
+        metadata: Information about the entity (keyword, ad group, campaign).
+        impression_share: Your share of impressions as a percentage range.
+        low_impression_share: Low end of impression share range.
+        high_impression_share: High end of impression share range.
         rank: Your rank compared to competitors.
+        low_rank: Low end of rank range.
+        high_rank: High end of rank range.
+        search_popularity: Popularity of the search term (0-5 scale).
     """
 
     model_config = ConfigDict(populate_by_name=True, extra="ignore")
@@ -357,3 +362,130 @@ class ImpressionShareReportRow(BaseModel):
     rank: int | None = None
     low_rank: int | None = Field(default=None, alias="lowRank")
     high_rank: int | None = Field(default=None, alias="highRank")
+    search_popularity: int | None = Field(default=None, alias="searchPopularity")
+
+
+class ImpressionShareDateRange(StrEnum):
+    """Date range options for weekly impression share reports."""
+
+    LAST_WEEK = "LAST_WEEK"
+    LAST_2_WEEKS = "LAST_2_WEEKS"
+    LAST_4_WEEKS = "LAST_4_WEEKS"
+
+
+class ImpressionShareReportStatus(StrEnum):
+    """Status of an impression share report."""
+
+    QUEUED = "QUEUED"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+
+
+class ImpressionShareReportRequest(BaseModel):
+    """Request model for creating an impression share report.
+
+    Impression share reports are async - you create a report request,
+    then poll for results.
+
+    Example:
+        Create a daily impression share report::
+
+            request = ImpressionShareReportRequest(
+                name="my_report",
+                start_time=date(2024, 1, 1),
+                end_time=date(2024, 1, 31),
+                granularity=GranularityType.DAILY,
+            )
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    name: str = "impression_share_report"
+    start_time: date = Field(alias="startTime")
+    end_time: date = Field(alias="endTime")
+    granularity: GranularityType = GranularityType.DAILY
+    date_range: ImpressionShareDateRange | None = Field(default=None, alias="dateRange")
+    selector: dict[str, Any] | None = None
+    return_records_with_no_metrics: bool = Field(default=True, alias="returnRecordsWithNoMetrics")
+    return_row_totals: bool = Field(default=False, alias="returnRowTotals")
+    return_grand_totals: bool = Field(default=False, alias="returnGrandTotals")
+
+
+class ImpressionShareReport(BaseModel):
+    """An impression share report with metadata and rows.
+
+    Attributes:
+        id: The report ID.
+        name: The report name.
+        state: Current state of the report (QUEUED, RUNNING, COMPLETED, FAILED).
+        start_time: Report start date.
+        end_time: Report end date.
+        granularity: Time granularity (DAILY or WEEKLY).
+        row: List of report rows with impression share data.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    id: int
+    name: str | None = None
+    state: ImpressionShareReportStatus | str = Field(alias="state")
+    start_time: str | None = Field(default=None, alias="startTime")
+    end_time: str | None = Field(default=None, alias="endTime")
+    granularity: GranularityType | str | None = None
+    date_range: str | None = Field(default=None, alias="dateRange")
+    row: list[ImpressionShareReportRow] = Field(default_factory=list)
+    grand_totals: GrandTotals | None = Field(default=None, alias="grandTotals")
+
+    @property
+    def is_complete(self) -> bool:
+        """Check if the report has finished generating."""
+        return self.state == ImpressionShareReportStatus.COMPLETED
+
+    @property
+    def is_failed(self) -> bool:
+        """Check if the report generation failed."""
+        return self.state == ImpressionShareReportStatus.FAILED
+
+    def to_dataframe(self) -> "pd.DataFrame":
+        """Convert impression share report to a pandas DataFrame.
+
+        Returns:
+            A DataFrame with impression share data.
+
+        Raises:
+            ImportError: If pandas is not installed.
+        """
+        try:
+            import pandas as pd
+        except ImportError:
+            raise ImportError(
+                "pandas is required for to_dataframe(). "
+                "Install with: pip install asa-api-client[pandas]"
+            ) from None
+
+        rows_data: list[dict[str, Any]] = []
+
+        for row in self.row:
+            row_data: dict[str, Any] = {}
+
+            if row.metadata:
+                meta_dict = row.metadata.model_dump(by_alias=False, exclude_none=True)
+                if meta_dict.get("bid_amount"):
+                    row_data["bid"] = meta_dict["bid_amount"].get("amount")
+                    row_data["currency"] = meta_dict["bid_amount"].get("currency")
+                    del meta_dict["bid_amount"]
+                row_data.update(meta_dict)
+
+            # Add impression share fields
+            row_data["impression_share"] = row.impression_share
+            row_data["low_impression_share"] = row.low_impression_share
+            row_data["high_impression_share"] = row.high_impression_share
+            row_data["rank"] = row.rank
+            row_data["low_rank"] = row.low_rank
+            row_data["high_rank"] = row.high_rank
+            row_data["search_popularity"] = row.search_popularity
+
+            rows_data.append(row_data)
+
+        return pd.DataFrame(rows_data)