Grundlagen der AdUp API

Überblick

Mit unserer AdUp API kannst du dich zurücklehnen und alle Daten deines Kontos automatisch in dein bevorzugetes BI System überführen.

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'

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'

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'

• 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'

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

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"

{
  "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"

{
  "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"

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.

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

"date_range": {

    "min": "2021-10-29",

    "max": "2021-10-29"

  },

  "date_range_type": "CUSTOM_DATE"

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

Site 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​​​​​​​.