Grundlagen AdUp API

Vorgehen

Vorab

Um die AdUp API nutzen zu können, erstelle dir einen Zugang. Gehe dafür in deinem Konto auf Profil oder lies genauer im passenden Support Artikel nach.

1. Schritt

Erhalte deine API-Login-Daten (z.B. über das Frontend).

2. Schritt

Hole dir an der API via OAUTH einen Access Token.

3. Schritt

Greife nun mit dem Access Token auf die Reports Route zu. Schaue dir dafür die interaktive Doku an.

4. Schritt

Richte anschließend deine persönlichen API Anfragen ein. Hierzu findest du Code Beispiele, Beschreibung aller Felder sowie Hinweise und Links zu allen möglichen Reports weiter unten in diesem Artikel.

Authentifizierung & Access Token

Schritt 1: API-Zugangsdaten erhalten

Stellen Sie sicher, dass Sie über Ihre API-Zugangsdaten verfügen.

Schritt 2: Access-Token anfordern

Senden Sie eine HTTP-POST-Anfrage an den Token-Endpoint https://api.adup-tech.com/v202101/oauth2/token. Beispiel:

curl -X POST \
  https://api.adup-tech.com/v202101/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=IHRE_CLIENT_ID&client_secret=IHR_CLIENT_SECRET'

Parameter:

grant_type: Der Typ des Grants, z. B. client_credentials.
client_id: Ihre Client-ID.
client_secret: Ihr Client-Secret.

Schritt 3: Access-Token verwenden

Nach erfolgreicher Authentifizierung erhalten Sie eine Antwort mit dem Access-Token. Diesen Token können Sie verwenden, um auf geschützte Ressourcen der API zuzugreifen, indem Sie ihn in den HTTP-Header Ihrer API-Anfragen aufnehmen:

curl -X GET \
  https://api.adup-tech.com/v202101/ihre-api-endpoint \
  -H 'Authorization: Bearer IHR_ACCESS_TOKEN'

Ersetzen Sie IHR_ACCESS_TOKEN durch den erhaltenen Token und passen Sie die URL entsprechend an.

Zusätzliche Hinweise:

Beachten Sie, dass Access-Tokens eine begrenzte Gültigkeitsdauer haben und regelmäßig erneuert werden müssen.
Antworten erfolgen im JSON Format, weitere Informationen: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept
Die Nutzung von Postman ist hier beschrieben: https://learning.postman.com/docs/sending-requests/authorization/oauth-20/#using-client-credentials

Report Anfrage

Code

{
  "report_name": "Test Report",
  "report_type": "CAMPAIGN_PERFORMANCE_REPORT",
  "select": [
    "Month",
    "CampaignName",
    "Clicks"
  ],
  "conditions": [
    {
      "field": "Clicks",
      "operator": "GREATER_THAN",
      "values": [
        "0"
      ]
    }
  ],
  "download_format": "JSON",
  "date_range_type": "LAST_MONTH"
}

Feld	Beschreibung	Beispiel
report_name	Selbst gewählter Name des Reports.
report_type	Der Reporttyp, der für den Report benutzt werden soll. Siehe unten 'API Reports'
select	Liste mit Feldern, die im Report ausgegeben werden sollen. Die möglichen Felder hängen vom benutzten Reporttyp ab. Siehe unten 'API Reports', um die möglichen Felder zu erfahren.
conditions	Liste von Filtern um die im Report enthaltenen Zeilen einzuschränken. Ein Filter besteht aus field, operator und values
download_format	Format in dem der Report heruntergeladen wird. Aktuell ist nur JSON möglich
date_range_type	Der Datumsbereich für den der Report erstellt werden soll. Siehe unten 'Datumsbereiche'
date_range	Wenn date_range_type auf CUSTOM_DATE gestellt wurde, gibt dies hier den Datumsbereich an, für den der Report erstellt werden soll. Siehe unten 'Datumsbereiche'

Hinweise

Segmentierung

Um Statistiken mit einem höheren Detailgrad zu erhalten, können sie Segmentierung verwenden.

Um z.B. die Statistiken nur für Mobile Geräte zu erhalten, müssen sie nach Gerätetyp filtern

In diesem Fall möchten Sie Ihren Bericht nach DeviceType segmentieren. Wenn Sie z. B. das Feld Device zu einem Campaign Performance Report hinzufügen, erhalten Sie einen Report mit einer Zeile für jede Kampagnen- und Gerätetypkombination und den statistischen Werten (Impressionen, Klicks, Conversions usw.), die auf diese aufgeteilt sind. Beachten Sie, dass die Anzahl der Zeilen für jedes zusätzliche Segmentfeld, das in Ihrem Bericht enthalten ist, exponentiell ansteigen kann.

Implizite Segmentierung Jeder Report ist nach einem Schlüssel gruppiert. Zum Beispiel ist der Campaign Performance Report implizit nach CampaignId segmentiert.

Zeilen ohne Metrik

Der Report kann Zeilen enthalten, die keine Werte in den Metriken vorweisen. Die Ursache können nicht auslieferbare Elemente oder innerhalb des abgefragten Zeitraums pausierte Elemente sein.

Um Zeilen ohne Metriken zu erhalten kann im Header includeZeroImpressions auf true (Default) gesetzt werden. Dies kann benutzt werden, um z.B. einen Strukturreport zu erstellen, der alle verfügbaren Elemente des Kontos enthält, zu erstellen.

Um die Anzahl der Zeilen bei vielen Elementen ohne zu verringern, sollte includeZeroImpressions allerdings auf false gesetzt werden. Alternativ kann auch ein Filter auf Metriken in conditions benutzt werden.

Datumsbereiche

Für jeden date_range_type außer CUSTOM_DATE ist nur date_range_type erforderlich.

Datumsbereich	Reports werden erstellt für...	Beispiel
TODAY	nur heute
YESTERDAY	nur gestern
LAST_7_DAYS	die letzten 7 Tage ohne den heutigen Tag
LAST_WEEK	der 7-tägige Zeitraum beginnend vom letzten Montag
LAST_BUSINESS_WEEK	die 5-tägige Geschäftswoche, Montag bis Freitag, der letzten Geschäftswoche
THIS_MONTH	alle Tage des aktuellen Monats
LAST_MONTH	alle Tage des letzten Monats
ALL_TIME	den gesamten verfügbare Zeitraum
CUSTOM_DATE	Einen eigenen Zeitraum. Siehe Eigener Zeitraum.	`"date_range": { "min": "2021-10-29", "max": "2021-10-29" }, "date_range_type": "CUSTOM_DATE"`
LAST_14_DAYS	die letzten 14 Tage ohne den heutigen Tag
LAST_30_DAYS	die letzten 30 tage ohne den heutigen Tag
THIS_WEEK_SUN_TODAY	der Zeitraum zwischen dem letzten Sonntag und heute
THIS_WEEK_MON_TODAY	der Zeitraum zwischen dem letzten Montag und heute
LAST_WEEK_SUN_SAT	der 7-tägige Zeitraum beginnend mit dem letzten Sonntag

Datentyp Micro Amount

Einige Felder haben den Datentyp Micro Amount, diese enthalten z.B. Währungswerte, die mit dem Faktor eine Million (1.000.000) multipliziert wurden.

Beispiel: Ein Wert von 123,4567 EUR werden in dem Feld als 123456700 ausgegeben.

API Reports

Derzeit bieten wir vier verschiedene Reports an, die über die API individualisiert abgerufen werden können.

Account Performance Report (Advertiser) Dokumentation

Ad Performance Report (Advertiser) Dokumentation

Campaign Performance Report (Advertiser) Dokumentation

Direct Placement Performance Report (Advertiser) Dokumentation

Placement Layout Performance Report (Publisher) Dokumentation

Weitere Scopes und Routen

Du hast in deinem API Zugang weitere Scopes neben dem Reporting ausgewählt? Um die passenden Routen und Informationen zu bekommen, melde dich bei deinem AdUp Ansprechpartner oder schreib und über support(at)adup-tech.com.

Grundlagen der AdUp API