> ## Documentation Index
> Fetch the complete documentation index at: https://docs.growthchannel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geo Report

> Get geographic performance data aggregated by location.

<Warning>Maximum date range 365 days</Warning>

<Note>
  This endpoint is protected and requires an agency API key for access.
</Note>

<RequestExample>
  ```bash Country-level report theme={null}
    curl --request GET \
      --url https://api.growthchannel.io/geo/?date_from=2024-01-01&date_to=2024-01-07&advertiser_id=544&breakout=country
  ```

  ```bash Region-level report theme={null}
    curl --request GET \
      --url https://api.growthchannel.io/geo/?date_from=2024-01-01&date_to=2024-01-07&advertiser_id=544&breakout=region
  ```

  ```bash Zip code-level report theme={null}
    curl --request GET \
      --url https://api.growthchannel.io/geo/?date_from=2024-01-01&date_to=2024-01-07&advertiser_id=544&breakout=zip_code
  ```
</RequestExample>

<CardGroup>
  <Card title="Method" icon="puzzle-piece">
    `GET`
  </Card>

  <Card title="Endpoint" icon="link">
    `/geo/`
  </Card>
</CardGroup>

## Headers

<ParamField header="X-Api-Key" type="string" required>
  The agency's API key for authorization. Contact an admin to get one.
</ParamField>

## Parameters

<ParamField path="date_from" type="string" required>
  Start date in YYYY-MM-DD format.
</ParamField>

<ParamField path="date_to" type="string" required>
  End date in YYYY-MM-DD format.
</ParamField>

<ParamField path="advertiser_id" type="integer" required>
  The unique identifier for the advertiser.
</ParamField>

<ParamField path="page" type="integer" default="0">
  Page number for pagination.
</ParamField>

<ParamField path="breakout" type="string" default="country">
  Geographic breakdown level (country/region/zip\_code).
</ParamField>

<ParamField path="campaign_id" type="integer">
  Filter by a specific campaign ID.
</ParamField>

## Breakout Options

The `breakout` parameter determines the level of geographic detail in the report.

* `country`: Aggregates data by country.
* `region`: Aggregates data by state or region.
* `zip_code`: Aggregates data by postal code.

## Responses

<Tabs>
  <Tab title="200 OK Country">
    ```json theme={null}
    {
      "data": [
        {
          "country": "US",
          "impressions": 1000,
          "clicks": 50,
          "total_conversions": 0,
          "video_audio_views": 0,
          "video_audio_complete": 0,
          "total_revenue": 0.0,
          "total_spend": 0.005,
          "cpm": 5.126,
          "cpc": 0.0,
          "cpa": 0.0,
          "cpv": 0.005,
          "cpv_video": 0.0,
          "cpcv_video": 0.0,
          "roas": 0.0,
          "vcr": 0.0,
          "ctr": 0.0
        }
      ],
      "pagination": {
        "current_page": 0,
        "total_pages": 5,
        "total_count": 100
      },
      "breakout": "country"
    }
    ```

    <ResponseField name="data" type="array">
      An array of geographic performance objects. The location key (`country`, `region`, or `zip_code`) depends on the `breakout` parameter used in the request.
    </ResponseField>

    <ResponseField name="pagination" type="object">
      An object containing pagination details.
    </ResponseField>
  </Tab>

  <Tab title="200 OK Region">
    ```json theme={null}
    {
      "data": [
        {
          "country": "US",
          "region": "Jalisco",
          "impressions": 1000,
          "clicks": 50,
          "total_conversions": 0,
          "video_audio_views": 0,
          "video_audio_complete": 0,
          "total_revenue": 0.0,
          "total_spend": 0.005,
          "cpm": 5.126,
          "cpc": 0.0,
          "cpa": 0.0,
          "cpv": 0.005,
          "cpv_video": 0.0,
          "cpcv_video": 0.0,
          "roas": 0.0,
          "vcr": 0.0,
          "ctr": 0.0
        }
      ],
      "pagination": {
        "current_page": 0,
        "total_pages": 5,
        "total_count": 100
      },
      "breakout": "region"
    }
    ```

    <ResponseField name="data" type="array">
      An array of geographic performance objects. The location key (`country`, `region`, or `zip_code`) depends on the `breakout` parameter used in the request.
    </ResponseField>

    <ResponseField name="pagination" type="object">
      An object containing pagination details.
    </ResponseField>
  </Tab>

  <Tab title="200 OK ZIPCODE">
    ```json theme={null}
    {
      "data": [
        {
          "country": "US",
          "zip_code": "60074",
          "impressions": 1000,
          "clicks": 50,
          "total_conversions": 0,
          "video_audio_views": 0,
          "video_audio_complete": 0,
          "total_revenue": 0.0,
          "total_spend": 0.005,
          "cpm": 5.126,
          "cpc": 0.0,
          "cpa": 0.0,
          "cpv": 0.005,
          "cpv_video": 0.0,
          "cpcv_video": 0.0,
          "roas": 0.0,
          "vcr": 0.0,
          "ctr": 0.0
        }
      ],
      "pagination": {
        "current_page": 0,
        "total_pages": 5,
        "total_count": 100
      },
      "breakout": "region"
    }
    ```

    <ResponseField name="data" type="array">
      An array of geographic performance objects. The location key (`country`, `region`, or `zip_code`) depends on the `breakout` parameter used in the request.
    </ResponseField>

    <ResponseField name="pagination" type="object">
      An object containing pagination details.
    </ResponseField>
  </Tab>

  <Tab title="400 Bad Request">
    Returned if required query parameters are missing.
  </Tab>

  <Tab title="401 Unauthorized">
    Returned if the `X-Api-Key` header is missing or invalid.
  </Tab>

  <Tab title="500 Internal Server Error">
    Returned if there is an unexpected server error.
  </Tab>
</Tabs>