api.socialfetch.dev

{
  "description": "Standard success response envelope.",
  "properties": {
    "data": {
      "description": "Endpoint-specific response payload.",
      "properties": {
        "ads": {
          "description": "Ads returned for the requested company or advertiser. This array may be empty when the lookup resolves but no ads match the filters.",
          "items": {
            "description": "A single Google Ad Transparency company ad.",
            "properties": {
              "adUrl": {
                "description": "Public Google Ad Transparency URL for this creative when available.",
                "nullable": true,
                "type": "string"
              },
              "advertiserId": {
                "description": "Google Ad Transparency advertiser id.",
                "minLength": 1,
                "type": "string"
              },
              "advertiserName": {
                "description": "Advertiser display name when available.",
                "nullable": true,
                "type": "string"
              },
              "creativeId": {
                "description": "Google Ad Transparency creative id.",
                "minLength": 1,
                "type": "string"
              },
              "domain": {
                "description": "Advertiser domain when available.",
                "nullable": true,
                "type": "string"
              },
              "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"
              },
              "imageUrl": {
                "description": "Preview image URL when available.",
                "nullable": true,
                "type": "string"
              },
              "lastShown": {
                "description": "ISO-8601 timestamp for when the ad was last shown, when available.",
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "advertiserId",
              "creativeId",
              "format",
              "adUrl",
              "advertiserName",
              "domain",
              "imageUrl",
              "firstShown",
              "lastShown"
            ],
            "type": "object"
          },
          "type": "array"
        },
        "adsEstimate": {
          "description": "Estimated total number of matching ads when reported; otherwise null.",
          "minimum": 0,
          "nullable": true,
          "type": "integer"
        },
        "lookupStatus": {
          "description": "Whether the company or advertiser resolved for this request.",
          "enum": [
            "found",
            "not_found"
          ],
          "type": "string"
        },
        "page": {
          "description": "Pagination information for the current response.",
          "properties": {
            "hasMore": {
              "description": "Whether another page of ads can be requested.",
              "type": "boolean"
            },
            "nextCursor": {
              "description": "Cursor to pass as `cursor` in the next request when `hasMore` is true; otherwise null.",
              "nullable": true,
              "type": "string"
            }
          },
          "required": [
            "nextCursor",
            "hasMore"
          ],
          "type": "object"
        }
      },
      "required": [
        "lookupStatus",
        "ads",
        "adsEstimate",
        "page"
      ],
      "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"
}