Zum Hauptinhalt springen
Durchsuchen Sie die Meta-Werbebibliothek über die asynchrone Task-API und erhalten Sie JSON. Senden Sie taskType ADS mit platform meta_ad_library und einem Stichwort in query oder der Facebook-Seiten-ID eines Werbetreibenden in pageId. Eine Suche kostet 0.5 Credits je 30 gelieferte Anzeigen. Um die Seiten-ID eines Werbetreibenden über seinen Namen zu finden, senden Sie action advertisers.

Anfrage

Senden Sie den Task und fragen Sie dann GET /v1/async/task/{id} ab oder empfangen Sie den Webhook. Siehe Asynchrone Tasks. Eine Suche nach 30 Anzeigen ist meist in wenigen Sekunden fertig, eine Suche nach 500 Anzeigen in etwa einer Minute.

Parameter

  • action: search (Standard) oder advertisers, das Werbetreibende über ihren Namen findet.
  • query: Ein Stichwort. Es findet die Wörter im Text einer Anzeige in beliebiger Reihenfolge. Erforderlich, wenn pageId fehlt.
  • pageId: Die numerische Facebook-Seiten-ID eines Werbetreibenden, etwa 266556540473351. Sie listet seine Anzeigen und durchsucht sie zusammen mit query.
  • country: Wo die Anzeigen liefen, als zweistelliger Ländercode, oder ALL für alle Länder. Standard ist US.
  • activeStatus: active (Standard), inactive oder all.
  • limit: 1 bis 500 Anzeigen. Standard ist 30.
  • cursor: Der nextCursor einer früheren Antwort, um die folgenden Anzeigen zu lesen.
  • searchType: keyword_unordered (Standard) oder keyword_exact_phrase.
  • adType: all (Standard), political_and_issue_ads, housing_ads, employment_ads oder financial_products_and_services_ads.
  • mediaType: all (Standard), image, meme, image_and_meme, video oder none.
  • publisherPlatforms: Einer oder mehrere von facebook, instagram, audience_network, messenger, whatsapp und threads, als Array oder kommagetrennter Text.
  • contentLanguages: Ein oder mehrere zweistellige Sprachcodes.
  • startDate, endDate: YYYY-MM-DD. Behält die Anzeigen, die zwischen den beiden Tagen gezeigt wurden.
  • sortBy: impressions_high_to_low (Standard) oder most_recent. impressions_low_to_high setzt adType political_and_issue_ads voraus, die einzigen Anzeigen, die die Bibliothek so sortiert.
Ein Wert, den die Bibliothek nicht durchsuchen kann, wird mit 400 VALIDATION_ERROR abgelehnt, und details nennt das Feld.

Weitere Anzeigen lesen

Eine Antwort, nach der noch Anzeigen zu lesen sind, enthält nextCursor. Senden Sie ihn als cursor mit derselben Suche, um die nächsten Anzeigen zu erhalten, wieder bis zu limit. Die Positionen setzen die vorige Antwort fort, und nextCursor ist null, sobald die Bibliothek keine weiteren hat.
Ein Cursor gilt nur für die Suche, die ihn geliefert hat: Eine andere query, pageId, country, activeStatus oder ein anderer Filter wird mit 400 VALIDATION_ERROR abgelehnt, limit darf sich ändern. Der Cursor wächst mit den zuvor gelesenen Anzeigen, nach tausend Anzeigen auf etwa 14 KB; speichern Sie ihn als Text ohne Längenbegrenzung. Die Bibliothek listet eine Anzeige manchmal zweimal, daher kann eine Anzeige in einer späteren Antwort erneut erscheinen; libraryId unterscheidet die Wiederholungen.

Werbetreibende finden

action advertisers liefert die Facebook-Seiten der Werbetreibenden, deren Name zu query passt, so wie das Suchfeld der Bibliothek sie vorschlägt. Senden Sie die gewählte pageId, um die Anzeigen dieses Werbetreibenden zu durchsuchen.
Jeder Werbetreibende hat position, pageId, name, category, likeCount, verified (Metas blaues Abzeichen), country (das Land der Seite, wenn Meta es nennt, etwa die britische Seite einer globalen Marke), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified und libraryUrl, das seine Anzeigen in der Werbebibliothek öffnet. keywords listet die Suchen, die die Bibliothek für den Namen vorschlägt. Die Bibliothek sucht den Namen so, wie die Seite ihn schreibt: Shokz findet die Shokz-Seiten, 샥즈 findet keine. Ein Name, den keine Seite trägt, endet mit leerem advertisers. Eine Suche nach Werbetreibenden nimmt nur query und country und kostet 0.5 Credits.

Antwortbeispiel

Ergebnisfelder

  • Die Antwort wiederholt platform, action, country, query oder pageId, activeStatus und die übergebenen Filter.
  • totalCount ist die Zahl der passenden Anzeigen laut Bibliothek, die sie bei großen Suchen rundet. returnedCount zählt die Anzeigen in ads, hasMore ist true, wenn die Bibliothek weitere hat, die nextCursor liest, und libraryUrl öffnet dieselbe Suche in der Werbebibliothek.
  • Jede Anzeige hat position, libraryId, libraryUrl, isActive, startDate und endDate (Tage in UTC), platforms, versions (wie viele Anzeigen dieses Creative und diesen Text nutzen), format (IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES und andere), body, title, caption, linkUrl, linkDescription, ctaText, ctaType und categories (die Kategorien der Anzeige laut Bibliothek, etwa POLITICAL oder EMPLOYMENT).
  • Der Werbetreibende ist pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount und pageCategories. Anzeigen zu gesellschaftlichen Themen, Wahlen oder Politik ergänzen byline, wer die Anzeige bezahlt hat, und disclaimerLabel, und eine bezahlte Partnerschaft ergänzt die Seite des Partners in brandedContent.
  • Medien sind images (url, resizedUrl), videos (hdUrl, sdUrl, previewImageUrl) und cards, die Karten einer Karussell- oder Katalog-Anzeige, jeweils mit title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl und video. Die weiteren Texte, Links, Bilder und Videos einer dynamischen Anzeige stehen in extraTexts, extraLinks, extraImages und extraVideos.
  • Medien-URLs sind Links auf Metas CDN, die nach einigen Tagen ablaufen. Speichern Sie die Dateien, die Sie brauchen.
  • Katalog-Anzeigen (DPA, DCO) behalten in ihrem Text die Platzhalter der Bibliothek, etwa {{product.name}}.
  • spend, currency, impressions und reach erscheinen nur, wo die Bibliothek sie offenlegt: bei Anzeigen zu gesellschaftlichen Themen, Wahlen oder Politik und bei Anzeigen, die in der EU gezeigt wurden.
  • Eine Suche ohne passende Anzeigen wird mit leerem ads und totalCount 0 abgeschlossen.

Preis

Eine Suche reserviert beim Start 0.5 Credits je 30 Anzeigen, die limit anfragt, und kostet 0.5 Credits je 30 gelieferte Anzeigen, mindestens 0.5 Credits. Die Standardsuche nach 30 Anzeigen kostet 0.5 Credits, eine Suche mit limit 500 reserviert 8.5 Credits. Eine Suche nach Werbetreibenden kostet 0.5 Credits. Berechnet werden nur abgeschlossene Anfragen.

Siehe auch