Geo Report

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=region' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=zip_code' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country&with_date=true' \
    --header 'X-Api-Key: YOUR_API_KEY'

GET

geo

?date_from=

{date_from}

&date_to=

{date_to}

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=region' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=zip_code' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country&with_date=true' \
    --header 'X-Api-Key: YOUR_API_KEY'

Maximum date range 365 days

This endpoint is protected and requires an agency API key for access.

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=region' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=zip_code' \
    --header 'X-Api-Key: YOUR_API_KEY'

  curl --request GET \
    --url 'https://api.growthchannel.io/geo/?date_from=2026-01-01&date_to=2026-01-07&advertiser_id=544&breakout=country&with_date=true' \
    --header 'X-Api-Key: YOUR_API_KEY'

Method

GET

Endpoint

/geo/

Headers

string

required

The agency’s API key for authorization. Contact an admin to get one.

Parameters

string

required

Start date in YYYY-MM-DD format.

string

required

End date in YYYY-MM-DD format.

integer

Return data for one advertiser only. Omit to get all advertisers accessible to your key.

integer

Return data for one agency only. It must be your agency or an agency in your portfolio.

integer

Return data for one campaign only.

string

default:"country"

Geographic breakdown level: country, region, or zip_code.

boolean

default:"false"

Return one row per location per day, with a date field. Accepts true/false, 1/0, yes/no.

integer

default:"0"

Page number, starting at 1. Each page has 20 rows. Omit or send 0 to get all rows.

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.

Sorting

Rows are sorted by impressions (highest first). With with_date=true, rows are sorted by date (oldest first), then by impressions. This report does not accept sort_column, sort_order, or search.

Responses

{
  "data": [
    {
      "country": "US",
      "impressions": 1000,
      "clicks": 50,
      "total_conversions": 0,
      "video_audio_views": 0,
      "video_audio_complete": 0,
      "total_revenue": 0.0,
      "total_spend": 5.126,
      "cpm": 5.126,
      "cpc": 0.103,
      "cpa": 0.0,
      "cpv": 0.005,
      "cpv_video": 0.0,
      "cpcv_video": 0.0,
      "roas": 0.0,
      "vcr": 0.0,
      "ctr": 5.0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 100
  },
  "breakout": "country",
  "with_date": false
}

array

An array of geographic performance objects. The location keys depend on breakout: country; country and region; or country and zip_code. With with_date=true, each row starts with date.

Show object

string

The day. Present only when with_date=true.

string

Country code.

string

State or region. Present only when breakout=region.

string

Postal code. Present only when breakout=zip_code.

integer

Delivery counts.

number

Conversion revenue and spend.

number

Calculated metrics. See Metrics.

object

An object containing pagination details.

Show object

integer

The requested page. 0 when all rows are returned.

integer

Total number of 20-row pages.

integer

Total number of records.

string

The breakout value used for the request.

boolean

The with_date value used for the request.

{
  "data": [
    {
      "country": "US",
      "region": "Illinois",
      "impressions": 1000,
      "clicks": 50,
      "total_conversions": 0,
      "video_audio_views": 0,
      "video_audio_complete": 0,
      "total_revenue": 0.0,
      "total_spend": 5.126,
      "cpm": 5.126,
      "cpc": 0.103,
      "cpa": 0.0,
      "cpv": 0.005,
      "cpv_video": 0.0,
      "cpcv_video": 0.0,
      "roas": 0.0,
      "vcr": 0.0,
      "ctr": 5.0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 100
  },
  "breakout": "region",
  "with_date": false
}

{
  "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": 5.126,
      "cpm": 5.126,
      "cpc": 0.103,
      "cpa": 0.0,
      "cpv": 0.005,
      "cpv_video": 0.0,
      "cpcv_video": 0.0,
      "roas": 0.0,
      "vcr": 0.0,
      "ctr": 5.0
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 100
  },
  "breakout": "zip_code",
  "with_date": false
}

{
  "data": [
    {
      "date": "2026-01-01",
      "country": "US",
      "impressions": 400,
      "clicks": 20,
      "total_conversions": 0,
      "video_audio_views": 0,
      "video_audio_complete": 0,
      "total_revenue": 0.0,
      "total_spend": 2.05,
      "cpm": 5.125,
      "cpc": 0.103,
      "cpa": 0.0,
      "cpv": 0.005,
      "cpv_video": 0.0,
      "cpcv_video": 0.0,
      "roas": 0.0,
      "vcr": 0.0,
      "ctr": 5.0
    }
  ],
  "pagination": {
    "current_page": 0,
    "total_pages": 1,
    "total_count": 7
  },
  "breakout": "country",
  "with_date": true
}

Returned if a parameter is missing or invalid. See Errors for all messages.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid breakout parameter",
    "details": {
      "breakout": "city",
      "valid_options": ["country", "region", "zip_code"]
    },
    "request_id": "..."
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "with_date must be a boolean (true/false, 1/0, yes/no)",
    "details": {
      "with_date": "daily"
    },
    "request_id": "..."
  }
}

Returned if the X-Api-Key header is missing or invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "details": {
      "field": "X-Api-Key",
      "issue": "invalid"
    },
    "request_id": "..."
  }
}

API documentation

Public endpoints

Method

Endpoint

Headers

Parameters

Breakout Options

Sorting

Responses

Method

Endpoint

​Headers

​Parameters

​Breakout Options

​Sorting

​Responses

Headers

Parameters

Breakout Options

Sorting

Responses