{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/adspendspy/main/json-schema/adspendspy-top-ads-response-schema.json",
  "title": "TopAdsResponse",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/adspendspy-api-openapi.json#/components/schemas/TopAdsResponse",
  "type": "object",
  "required": [
    "success",
    "data",
    "meta"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "data": {
      "type": "object",
      "required": [
        "totalSpend",
        "adCount",
        "matchedAdCount",
        "matchedTotalSpend"
      ],
      "properties": {
        "totalSpend": {
          "type": "number",
          "description": "Estimated spend in EUR of the sampled top ads."
        },
        "adCount": {
          "type": "integer",
          "description": "Sampled ads (at most 1,000)."
        },
        "mediaTypeStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "media_type",
              "count",
              "total_spend"
            ],
            "properties": {
              "media_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "count": {
                "type": "integer"
              },
              "total_spend": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
                "description": "Estimated spend in EUR. Decimal string."
              }
            }
          }
        },
        "durationStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "duration",
              "count",
              "total_spend"
            ],
            "properties": {
              "duration": {
                "type": "integer",
                "nullable": false
              },
              "count": {
                "type": "integer"
              },
              "total_spend": {
                "type": "number",
                "description": "Estimated spend in EUR."
              },
              "duration_range": {
                "type": "string"
              }
            }
          }
        },
        "maxDurationSpend": {
          "type": "number"
        },
        "genderStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "gender",
              "ad_count",
              "total_spend"
            ],
            "properties": {
              "gender": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ad_count": {
                "type": "integer"
              },
              "total_spend": {
                "type": "number",
                "description": "Estimated spend in EUR."
              },
              "total_reach": {
                "type": "integer"
              }
            }
          }
        },
        "ageStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "age_range",
              "ad_count",
              "total_spend"
            ],
            "properties": {
              "age_range": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ad_count": {
                "type": "integer"
              },
              "total_spend": {
                "type": "number",
                "description": "Estimated spend in EUR."
              },
              "total_reach": {
                "type": "integer"
              }
            }
          }
        },
        "ctaStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "cta_text",
              "count",
              "total_spend"
            ],
            "properties": {
              "cta_text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "count": {
                "type": "integer"
              },
              "total_spend": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
                "description": "Estimated spend in EUR. Decimal string."
              }
            }
          }
        },
        "hooksStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "hook_text",
              "ad_count",
              "total_spend"
            ],
            "properties": {
              "hook_text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ad_count": {
                "type": "integer"
              },
              "total_spend": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
                "description": "Estimated spend in EUR. Decimal string."
              },
              "hook_type": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        },
        "headlineStats": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "headline",
              "count",
              "total_spend"
            ],
            "properties": {
              "headline": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "count": {
                "type": "integer"
              },
              "total_spend": {
                "type": [
                  "string",
                  "null"
                ],
                "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
                "description": "Estimated spend in EUR. Decimal string."
              }
            }
          }
        },
        "matchedAdCount": {
          "type": "integer",
          "description": "All matching ads."
        },
        "matchedTotalSpend": {
          "type": "number",
          "description": "Estimated spend in EUR of all matching ads."
        }
      }
    },
    "meta": {
      "$ref": "#/$defs/SpendMeta"
    }
  },
  "$defs": {
    "SpendMeta": {
      "type": "object",
      "description": "How to read the spend figures in this response.",
      "required": [
        "currency",
        "spend_basis",
        "model_version",
        "timeframe",
        "timeframe_basis",
        "period_spend_available",
        "zero_spend_means",
        "demographics_basis"
      ],
      "properties": {
        "currency": {
          "type": "string",
          "enum": [
            "EUR"
          ]
        },
        "spend_basis": {
          "type": "string",
          "enum": [
            "latest_cumulative_estimate"
          ]
        },
        "model_version": {
          "type": "integer"
        },
        "timeframe": {
          "type": "string",
          "enum": [
            "all",
            "7d",
            "30d",
            "90d"
          ],
          "description": "Last-seen filter that was applied; never a period-spend calculation."
        },
        "timeframe_basis": {
          "type": "string",
          "enum": [
            "last_seen_at"
          ]
        },
        "period_spend_available": {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        "zero_spend_means": {
          "type": "string",
          "enum": [
            "unknown"
          ]
        },
        "demographics_basis": {
          "type": "string",
          "enum": [
            "latest_snapshot"
          ]
        },
        "sample_limit": {
          "type": "integer",
          "description": "Statistics only: creative breakdowns use at most this many top ads."
        },
        "sampled": {
          "type": "boolean",
          "description": "Statistics only: true when more ads matched than the sample holds."
        },
        "aggregate_scope": {
          "type": "string",
          "description": "Statistics only: which ads the matched totals cover."
        }
      }
    }
  }
}