api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "ad": {
          "description": "Ad details when found; otherwise null.",
          "nullable": true,
          "properties": {
            "advertiserId": {
              "description": "Google Ad Transparency advertiser id.",
              "minLength": 1,
              "type": "string"
            },
            "creativeId": {
              "description": "Google Ad Transparency creative id.",
              "minLength": 1,
              "type": "string"
            },
            "creativeRegions": {
              "description": "Regions where the creative ran.",
              "items": {
                "description": "Region where a Google Ad Library creative ran.",
                "properties": {
                  "regionCode": {
                    "description": "Two-letter region code when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "regionName": {
                    "description": "Human-readable region name when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "regionCode",
                  "regionName"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "firstShown": {
              "description": "ISO-8601 timestamp for when the ad was first shown, when available.",
              "nullable": true,
              "type": "string"
            },
            "format": {
              "description": "Creative format when available (text, image, or video).",
              "nullable": true,
              "type": "string"
            },
            "lastShown": {
              "description": "ISO-8601 timestamp for when the ad was last shown, when available.",
              "nullable": true,
              "type": "string"
            },
            "overallImpressions": {
              "description": "Overall impression range when available.",
              "nullable": true,
              "properties": {
                "max": {
                  "description": "Upper bound for impressions when available.",
                  "minimum": 0,
                  "nullable": true,
                  "type": "integer"
                },
                "min": {
                  "description": "Lower bound for impressions when available.",
                  "minimum": 0,
                  "nullable": true,
                  "type": "integer"
                }
              },
              "required": [
                "min",
                "max"
              ],
              "type": "object"
            },
            "regionStats": {
              "description": "Per-region impression and date stats.",
              "items": {
                "description": "Per-region stats for a Google Ad Library ad.",
                "properties": {
                  "firstShown": {
                    "description": "ISO-8601 timestamp for when the ad was first shown in this region, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "impressions": {
                    "description": "Impression range for this region when available.",
                    "nullable": true,
                    "properties": {
                      "max": {
                        "description": "Upper bound for impressions when available.",
                        "minimum": 0,
                        "nullable": true,
                        "type": "integer"
                      },
                      "min": {
                        "description": "Lower bound for impressions when available.",
                        "minimum": 0,
                        "nullable": true,
                        "type": "integer"
                      }
                    },
                    "required": [
                      "min",
                      "max"
                    ],
                    "type": "object"
                  },
                  "lastShown": {
                    "description": "ISO-8601 timestamp for when the ad was last shown in this region, when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "platformImpressions": {
                    "description": "Per-platform impression breakdowns when available.",
                    "items": {
                      "properties": {
                        "impressions": {
                          "description": "Impression range for this platform when available.",
                          "nullable": true,
                          "properties": {
                            "max": {
                              "description": "Upper bound for impressions when available.",
                              "minimum": 0,
                              "nullable": true,
                              "type": "integer"
                            },
                            "min": {
                              "description": "Lower bound for impressions when available.",
                              "minimum": 0,
                              "nullable": true,
                              "type": "integer"
                            }
                          },
                          "required": [
                            "min",
                            "max"
                          ],
                          "type": "object"
                        },
                        "platform": {
                          "description": "Platform label when available.",
                          "nullable": true,
                          "type": "string"
                        }
                      },
                      "required": [
                        "platform",
                        "impressions"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "regionCode": {
                    "description": "Two-letter region code when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "regionName": {
                    "description": "Human-readable region name when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "regionCode",
                  "regionName",
                  "firstShown",
                  "lastShown",
                  "impressions",
                  "platformImpressions"
                ],
                "type": "object"
              },
              "type": "array"
            },
            "variations": {
              "description": "Creative variations for this ad.",
              "items": {
                "description": "A creative variation for a Google Ad Library ad.",
                "properties": {
                  "allText": {
                    "description": "Combined visible text when available. Text may be OCR-extracted and imperfect.",
                    "nullable": true,
                    "type": "string"
                  },
                  "description": {
                    "description": "Ad description when available. Text may be OCR-extracted and imperfect.",
                    "nullable": true,
                    "type": "string"
                  },
                  "destinationUrl": {
                    "description": "Landing page or destination URL when available.",
                    "nullable": true,
                    "type": "string"
                  },
                  "headline": {
                    "description": "Ad headline when available. Text may be OCR-extracted and imperfect.",
                    "nullable": true,
                    "type": "string"
                  },
                  "imageUrl": {
                    "description": "Creative image URL when available.",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "destinationUrl",
                  "headline",
                  "description",
                  "allText",
                  "imageUrl"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "advertiserId",
            "creativeId",
            "format",
            "firstShown",
            "lastShown",
            "overallImpressions",
            "creativeRegions",
            "regionStats",
            "variations"
          ],
          "type": "object"
        },
        "lookupStatus": {
          "description": "Whether the ad was found in the Ad Transparency Library.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        }
      },
      "required": [
        "lookupStatus",
        "ad"
      ],
      "type": "object"
    },
    "meta": {
      "description": "Metadata describing the request and billing outcome.",
      "properties": {
        "cached": {
          "description": "True when served from shared response cache. Credits still apply (full endpoint price); Age header may be present.",
          "type": "boolean"
        },
        "creditsCharged": {
          "description": "Credits charged for this request.",
          "minimum": 0,
          "type": "integer"
        },
        "requestId": {
          "description": "Unique request identifier for tracing this API call.",
          "minLength": 1,
          "type": "string"
        },
        "version": {
          "description": "Public API version that served the response.",
          "enum": [
            "v1"
          ],
          "type": "string"
        }
      },
      "required": [
        "requestId",
        "creditsCharged",
        "version"
      ],
      "type": "object"
    }
  },
  "required": [
    "data",
    "meta"
  ],
  "type": "object"
}