{ "openapi": "3.1.0", "info": { "title": "Google Ad Library API", "version": "1.0.0", "description": "The ads running on Google Search, YouTube, Shopping, Maps and Play — creative versions, formats, run dates, the countries they ran in, and the media files — exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/google-ad-library" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-ads": { "post": { "operationId": "search-ads", "tags": [ "Ads" ], "summary": "Find the ads a brand is running", "description": "Find the ads run by the advertisers matching a brand or company name, or by an advertiser website when domain is given, across Google Search, YouTube, Shopping, Maps and Play. The query matches advertiser names, not the wording inside ads — Google publishes no searchable index of ad copy, so there is no full-text search over creative. The advertisers the query resolved to come back on matchedAdvertisers so you can confirm what it matched before trusting the ads. A name that matches nothing returns 404 rather than an empty list.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Advertiser or brand name to find ads for. This matches advertiser names, not ad wording." }, "domain": { "type": "string", "description": "Search by advertiser website instead of by name, for example nike.com." }, "advertiserLimit": { "type": "number", "description": "How many matching advertisers to pull ads from (max 10). Raise it when a brand name resolves to several registered advertisers.", "example": "1" }, "region": { "type": "string", "description": "Two-letter country code, or ANYWHERE.", "example": "ANYWHERE" }, "regions": { "type": "array", "items": { "type": "string" }, "description": "Several countries at once (max 20). Overrides region." }, "adFormat": { "type": "string", "description": "text, image, or video. Google publishes one format per ad." }, "surfaces": { "type": "array", "items": { "type": "string" }, "description": "Restrict to the Google surfaces the ad ran on: search, youtube, shopping, maps, play." }, "shownAfter": { "type": "string", "description": "Only ads shown on or after this YYYY-MM-DD date." }, "shownBefore": { "type": "string", "description": "Only ads shown on or before this YYYY-MM-DD date." }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "first_shown, days_shown, or none." }, "sortDirection": { "type": "string", "description": "asc or desc." } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "Nike", "region": "US", "surfaces": [ "youtube", "search" ], "adFormat": "video", "limit": 30 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The name the search ran with." }, "matchedAdvertisers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The advertisers the query resolved to, with their ids, verified country and approximate ad counts. Check this before trusting the ads — a common brand name can resolve to the wrong registered advertiser." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adId": { "type": "string", "description": "Ad id — the handle for ad-detail and ad-media, which also need the advertiserId." }, "adLibraryUrl": { "type": "string", "description": "Public Google Ad Library permalink for this ad." }, "advertiserId": { "type": "string", "description": "Advertiser running the ad." }, "advertiserName": { "type": "string", "description": "Advertiser name as Google publishes it." }, "format": { "type": "string", "description": "text, image, or video." }, "firstShownDate": { "type": "string", "description": "First day the ad was seen, as YYYY-MM-DD." }, "daysShown": { "type": "number", "description": "Days the ad was actually shown. Approximate, and lower than the span between its first and last day whenever the ad paused." }, "domain": { "type": "string", "description": "The advertiser's website, when Google reports it." }, "regions": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Countries the ad ran in with the last date seen in each. Populated on a single-ad lookup; empty on a listing." }, "variations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Each version of the creative. Google publishes ads as pictures of the rendered ad, not as separate headline and body text — see the note on ad-detail." }, "variationCount": { "type": "number", "description": "How many creative versions the ad carries." }, "previewImageUrl": { "type": "string", "description": "First picture of the ad across its versions, for a quick preview." } } }, "description": "The matching ads." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters this request actually ran with, after defaults were applied." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "approximateTotal": { "type": "object", "additionalProperties": true, "description": "Roughly how many ads match in total, as a { min, max } range. Google publishes counts as ranges, never exact figures." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for, which can exceed pagesScraped when the listing ran out." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a walk that stopped short, or a listing that may be incomplete. Read it before treating a result set as the whole picture." } }, "additionalProperties": false }, "examples": { "default": { "value": { "query": "Nike", "adCount": 30, "pagesScraped": 1, "hasNextPage": true, "approximateTotal": { "min": 1000, "max": 5000 }, "matchedAdvertisers": [ { "advertiserId": "AR01234567890123456789", "advertiserName": "Nike, Inc.", "countryCode": "US", "approximateAdCount": { "min": 1000, "max": 5000 } } ], "ads": [ { "adId": "CR01234567890123456789", "advertiserId": "AR01234567890123456789", "advertiserName": "Nike, Inc.", "format": "video", "firstShownDate": "2026-07-14", "daysShown": 48, "domain": "nike.com", "variationCount": 2 } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-ads": { "post": { "operationId": "advertiser-ads", "tags": [ "Ads" ], "summary": "Get every ad one advertiser runs", "description": "Return the Google Ad Library ads for a single advertiser, given an advertiser id, an Ad Library advertiser URL, or an advertiser name. Accepts the same region, format, surface and date filters as a brand search. Use this rather than search-ads once you hold an advertiser id: it skips the name-resolution step, so there is no risk of the wrong registered advertiser being matched.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Advertiser id, an Ad Library advertiser URL, or an advertiser name. An id or URL is exact; a name is resolved first and may match the wrong advertiser." }, "region": { "type": "string", "description": "Two-letter country code, or ANYWHERE.", "example": "ANYWHERE" }, "regions": { "type": "array", "items": { "type": "string" }, "description": "Several countries at once (max 20). Overrides region." }, "adFormat": { "type": "string", "description": "text, image, or video. Google publishes one format per ad." }, "surfaces": { "type": "array", "items": { "type": "string" }, "description": "Restrict to the Google surfaces the ad ran on: search, youtube, shopping, maps, play." }, "shownAfter": { "type": "string", "description": "Only ads shown on or after this YYYY-MM-DD date." }, "shownBefore": { "type": "string", "description": "Only ads shown on or before this YYYY-MM-DD date." }, "limit": { "type": "number", "description": "Maximum ads returned (max 2000), or -1 for everything available.", "example": "30" }, "pages": { "type": "number", "description": "Pages of results to collect in one request (max 100), or -1 for the maximum allowed." }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "sortBy": { "type": "string", "description": "first_shown, days_shown, or none." }, "sortDirection": { "type": "string", "description": "asc or desc." } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "AR01234567890123456789", "region": "US", "pages": 3 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiserId": { "type": "string", "description": "The resolved advertiser id." }, "advertiserName": { "type": "string", "description": "The advertiser name Google publishes." }, "ads": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "adId": { "type": "string", "description": "Ad id — the handle for ad-detail and ad-media, which also need the advertiserId." }, "adLibraryUrl": { "type": "string", "description": "Public Google Ad Library permalink for this ad." }, "advertiserId": { "type": "string", "description": "Advertiser running the ad." }, "advertiserName": { "type": "string", "description": "Advertiser name as Google publishes it." }, "format": { "type": "string", "description": "text, image, or video." }, "firstShownDate": { "type": "string", "description": "First day the ad was seen, as YYYY-MM-DD." }, "daysShown": { "type": "number", "description": "Days the ad was actually shown. Approximate, and lower than the span between its first and last day whenever the ad paused." }, "domain": { "type": "string", "description": "The advertiser's website, when Google reports it." }, "regions": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Countries the ad ran in with the last date seen in each. Populated on a single-ad lookup; empty on a listing." }, "variations": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Each version of the creative. Google publishes ads as pictures of the rendered ad, not as separate headline and body text — see the note on ad-detail." }, "variationCount": { "type": "number", "description": "How many creative versions the ad carries." }, "previewImageUrl": { "type": "string", "description": "First picture of the ad across its versions, for a quick preview." } } }, "description": "The matching ads." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters this request actually ran with, after defaults were applied." }, "adCount": { "type": "number", "description": "Number of ads in this response." }, "approximateTotal": { "type": "object", "additionalProperties": true, "description": "Roughly how many ads match in total, as a { min, max } range. Google publishes counts as ranges, never exact figures." }, "pagesScraped": { "type": "number", "description": "Pages actually walked. Each page counts as one request against your plan." }, "pagesRequested": { "type": "number", "description": "Pages the request asked for, which can exceed pagesScraped when the listing ran out." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more results are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result — a walk that stopped short, or a listing that may be incomplete. Read it before treating a result set as the whole picture." } }, "additionalProperties": false }, "examples": { "default": { "value": { "advertiserId": "AR01234567890123456789", "advertiserName": "Nike, Inc.", "adCount": 84, "pagesScraped": 3, "pagesRequested": 3, "hasNextPage": true, "nextCursor": "eyJwYWdlIjozfQ", "ads": [], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/search-advertisers": { "post": { "operationId": "search-advertisers", "tags": [ "Advertisers" ], "summary": "Find advertisers by name", "description": "Look up advertisers whose registered name matches a brand or company name. Returns the advertiser id the other routes need, the country each advertiser completed its Google verification in, and roughly how many ads it is running as a range. Several distinct advertisers can share a name — a global brand often registers one per market — so compare the ad counts and countries to tell them apart. Matching advertiser websites come back on domains, ready to pass to search-ads as the domain filter.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Advertiser or brand name to look up." }, "region": { "type": "string", "description": "Two-letter country code, or ANYWHERE.", "example": "ANYWHERE" }, "regions": { "type": "array", "items": { "type": "string" }, "description": "Several countries at once (max 20)." }, "limit": { "type": "number", "description": "Maximum advertisers returned (max 100), or -1 for everything available.", "example": "30" }, "includeDomains": { "type": "boolean", "description": "Also return advertiser websites matching the name.", "example": "true" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "Nike", "region": "US", "limit": 10 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertisers": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "advertiserId": { "type": "string", "description": "Advertiser id — the handle for advertiser-ads and advertiser-profile." }, "advertiserName": { "type": "string", "description": "Registered advertiser name." }, "countryCode": { "type": "string", "description": "Country the advertiser is registered in." }, "approximateAdCount": { "type": "object", "additionalProperties": true, "description": "Ads this advertiser has in the requested country, as a { min, max } range. Google never publishes an exact figure." }, "adLibraryUrl": { "type": "string", "description": "Public Ad Library link for the advertiser." } } }, "description": "Matching advertisers." }, "advertiserCount": { "type": "number", "description": "Number of advertisers in this response." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Advertiser websites matching the name, usable as the domain filter on search-ads." }, "regions": { "type": "array", "items": { "type": "string" }, "description": "The countries the lookup ran against." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result, such as a list that may be incomplete." } }, "additionalProperties": false }, "examples": { "default": { "value": { "advertiserCount": 2, "advertisers": [ { "advertiserId": "AR01234567890123456789", "advertiserName": "Nike, Inc.", "countryCode": "US", "approximateAdCount": { "min": 1000, "max": 5000 } }, { "advertiserId": "AR09876543210987654321", "advertiserName": "Nike Retail B.V.", "countryCode": "NL", "approximateAdCount": { "min": 50, "max": 100 } } ], "domains": [ "nike.com" ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/advertiser-profile": { "post": { "operationId": "advertiser-profile", "tags": [ "Advertisers" ], "summary": "Get an advertiser's verified identity", "description": "Read the name an advertiser advertises under, the legal name on its completed Google advertiser verification, and the country it verified in. This is the whole of what Google publishes about an advertiser: there is no category, follower count, description or spend total in the Ads Transparency Center, so this endpoint is deliberately narrow. Use it to confirm who is actually behind a brand name before attributing a campaign to them.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser": { "type": "string", "description": "Advertiser id, an Ad Library advertiser URL, or an advertiser name." }, "region": { "type": "string", "description": "Two-letter country code." } }, "additionalProperties": false, "required": [ "advertiser" ] }, "examples": { "default": { "value": { "advertiser": "AR01234567890123456789" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "additionalProperties": true, "description": "The advertiser's published identity record.", "properties": { "advertiserId": { "type": "string", "description": "Advertiser id." }, "advertiserName": { "type": "string", "description": "Name the advertiser advertises under." }, "verifiedName": { "type": "string", "description": "Legal name on the advertiser's completed identity verification. Often differs from the brand name." }, "verifiedCountryCode": { "type": "string", "description": "Country the advertiser verified in." }, "countryCode": { "type": "string", "description": "Country the profile was read for." }, "adLibraryUrl": { "type": "string", "description": "Public Ad Library link for the advertiser." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result." } }, "additionalProperties": false }, "examples": { "default": { "value": { "profile": { "advertiserId": "AR01234567890123456789", "advertiserName": "Nike", "verifiedName": "Nike, Inc.", "verifiedCountryCode": "US", "countryCode": "US", "adLibraryUrl": "https://adstransparency.google.com/advertiser/AR01234567890123456789" }, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-detail": { "post": { "operationId": "ad-detail", "tags": [ "Ads" ], "summary": "Get one ad in full", "description": "Read everything the Google Ad Library shows for a single ad: every version of the creative, the format, the countries it ran in with the last date it was seen in each, and when it first ran. Pass the full Ad Library ad URL, or an ad id together with its advertiser — an ad id alone is not enough to locate an ad. Note what Google does not publish: ads come back as pictures of the rendered ad, not as separate headline, body and call-to-action fields, so there is no ad copy to read as text. A variation whose kind is rendered has no image at all and only draws in a browser; send it to ad-media to resolve its files.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad id, or an Ad Library ad URL." }, "advertiser": { "type": "string", "description": "The ad’s advertiser. Required unless ad is a full Ad Library ad URL." }, "region": { "type": "string", "description": "Two-letter country code." }, "includeRunDates": { "type": "boolean", "description": "Also report when the ad first ran and how many days it ran. Costs an extra upstream lookup; turn it off if you only need the creative.", "example": "true" } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "CR01234567890123456789", "advertiser": "AR01234567890123456789", "includeRunDates": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "adId": { "type": "string", "description": "The resolved ad id." }, "advertiserId": { "type": "string", "description": "The advertiser running the ad." }, "ad": { "type": "object", "additionalProperties": true, "description": "The full ad record.", "properties": { "format": { "type": "string", "description": "text, image, or video." }, "firstShownDate": { "type": "string", "description": "First day the ad was seen, when includeRunDates is on." }, "daysShown": { "type": "number", "description": "Days the ad was actually shown. Approximate, and lower than the calendar span whenever the ad paused." }, "regions": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Every country the ad ran in, each with regionCode and the last date it was seen there." }, "variations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "description": "image carries a picture of the rendered ad at imageUrl. rendered has no image and only draws in a browser — resolve its files with ad-media." }, "imageUrl": { "type": "string", "description": "Picture of the ad, present when kind is image." }, "previewUrl": { "type": "string", "description": "Browser preview, present when kind is rendered." } } }, "description": "Each version of the creative." }, "variationCount": { "type": "number", "description": "How many creative versions the ad carries." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result, such as run dates that could not be resolved." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adId": "CR01234567890123456789", "advertiserId": "AR01234567890123456789", "ad": { "format": "video", "firstShownDate": "2026-07-14", "daysShown": 48, "variationCount": 2, "regions": [ { "regionCode": "US", "lastShownDate": "2026-08-31" }, { "regionCode": "CA", "lastShownDate": "2026-08-19" } ], "variations": [ { "index": 0, "kind": "rendered", "previewUrl": "https://adstransparency.google.com/..." } ] }, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/ad-media": { "post": { "operationId": "ad-media", "tags": [ "Media" ], "summary": "Get an ad's videos and images", "description": "Resolve the video, image and thumbnail files on an ad, including the YouTube video where there is one. Each asset carries a downloadUrl served by this API, which is the reliable way to fetch a video: Google's own video URLs are signed, expire, and only play back from the address they were issued to. Set probe to confirm each asset is still downloadable and report its size and content type, or inline to get the bytes base64-encoded — which is refused for assets over the inline size limit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ad": { "type": "string", "description": "Ad id, or an Ad Library ad URL." }, "advertiser": { "type": "string", "description": "The ad’s advertiser. Required unless ad is a full Ad Library ad URL." }, "region": { "type": "string", "description": "Two-letter country code." }, "kinds": { "type": "array", "items": { "type": "string" }, "description": "image, video, and/or thumbnail.", "example": "all three" }, "probe": { "type": "boolean", "description": "Confirm each asset is still downloadable and report its size and content type." }, "inline": { "type": "boolean", "description": "Return the bytes base64-encoded. Refused for assets over the inline size limit — use downloadUrl for anything large." } }, "additionalProperties": false, "required": [ "ad" ] }, "examples": { "default": { "value": { "ad": "CR01234567890123456789", "advertiser": "AR01234567890123456789", "kinds": [ "video", "image" ], "probe": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "kind": { "type": "string", "description": "image, video, or thumbnail." }, "url": { "type": "string", "description": "Google’s own URL. A video URL is signed, expires, and only plays back from the address it was issued to." }, "downloadUrl": { "type": "string", "description": "Serves the same file through this API without the expiry — pass it to GET /media to stream the bytes." }, "quality": { "type": "string", "description": "original, snapshot, or preview." }, "variationIndex": { "type": "number", "description": "Which creative version the asset belongs to." }, "youtubeVideoId": { "type": "string", "description": "Set when the video is hosted on YouTube." }, "watchUrl": { "type": "string", "description": "Page a human can watch the video on." }, "contentType": { "type": "string", "description": "MIME type. Populated only when probe or inline was set." }, "contentLength": { "type": "number", "description": "Size in bytes. Populated only when probe or inline was set." }, "base64": { "type": "string", "description": "The bytes themselves. Populated only when inline was set." } } }, "description": "The ad’s media assets." }, "assetCount": { "type": "number", "description": "Number of assets in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this particular result, such as an asset that could not be resolved." } }, "additionalProperties": false }, "examples": { "default": { "value": { "adId": "CR01234567890123456789", "assetCount": 2, "assets": [ { "kind": "video", "quality": "original", "youtubeVideoId": "dQw4w9WgXcQ", "watchUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "contentType": "video/mp4", "contentLength": 4182773 } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Media" ], "summary": "Download an ad media file", "description": "Stream an ad's actual video or image bytes, using a url taken from an asset returned by /ad-media. Only Google's own ad-serving hosts are accepted. HTTP Range requests are supported, so video seeking works in a player. This is a GET with query parameters, not a JSON POST, and it bills as one request. Use it rather than the raw Google URL for video: the raw URL is signed and expires.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Media URL as returned on an ad asset. Passed as a query parameter. Only Google ad-serving hosts are accepted.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse an Ad Library URL", "description": "Turn any Google Ad Library URL into the structured filters it encodes — whether it points at one ad, one advertiser or one website, plus the region, creative format, Google surfaces, date range and political-only flag carried in its query string. Only the identifier matching kind is populated. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Ad Library URL, to be parsed into structured filters." } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://adstransparency.google.com/advertiser/AR01234567890123456789?region=US" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: ad, advertiser, domain, or unknown." }, "adId": { "type": "string", "description": "Present when kind is ad." }, "advertiserId": { "type": "string", "description": "Present when kind is ad or advertiser." }, "domain": { "type": "string", "description": "Present when kind is domain." }, "region": { "type": "string", "description": "Region filter carried in the URL." }, "format": { "type": "string", "description": "Creative format filter carried in the URL." }, "surfaces": { "type": "array", "items": { "type": "string" }, "description": "Google surfaces carried in the URL." }, "shownAfter": { "type": "string", "description": "Start of the date range carried in the URL." }, "shownBefore": { "type": "string", "description": "End of the date range carried in the URL." }, "politicalOnly": { "type": "boolean", "description": "Whether the URL restricts to political and issue ads." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "advertiser", "advertiserId": "AR01234567890123456789", "adId": null, "domain": null, "region": "US", "format": null, "surfaces": [], "politicalOnly": false } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }