API
Keywords:
api, schnittstelle, zugriff, upload
Deutsch Datum:
18.11.2016
verfügbare Sprachen:
English
English

Der AdServer bietet die Möglichkeit via einer API automatisiert Daten an Ihn zu senden und damit neue Datensätze zu erzeugen bzw. bestehende Datensätze zu verändern.

 

WICHTIG: Der Zugriff via API kann zu schweren Fehlern in der Einstellung und im Betrieb des AdServers führen. Sollten Sie die API verwenden wollen ist es daher dringend ratsam dies konkret mit Ihrem jeweiligen technischen Ansprechpartner zu koordinieren! 

API-Zugriff

Der Zugriff auf die API erfolgt jeweils über die URL des Formulars das Sie auch im AdSpirit Control verwenden. Wollen Sie etwa eine Kampagne via API anlegen gehen Sie am einfachsten in ihr AdSpirit Control, dort auf Kampagne bearbeiten und lassen sich von Ihrem Browser die URL des Formulars anzeigen (in diesem Fall http://[AdServer-URL]/control/kampagnen_edit.php); siehe auch unten Liste der API URLs. Darüber hinaus gibt es einige spezielle APIs die einzelne Funktionen abdecken.

Alle URLs können per HTTP GET und POST angesprochen werden.

Authentifizierung

Zur Authentifizierung können die Parameter kname (Username) und kpass (Passwort) oder kmd (Sessionkey) verwendet werden.

Um einen Sessionkey zu erzeugen verwenden Sie bitte die API /control/api_kmd.php und übergeben Sie Username + Password (kname/kpass) sowie type=X wobei X für die Art des Logins steht (0=Control, 1=Publisher, 2=Advertiser). Bitte beachten Sie, dass ein über diese API erzeugter Schlüssel ein Ablaufdatum von 1 Jahr besitzt.

Funktionen der API

Jede API stellt mehrere Funktionen zur Verfügung:

  • Informationen zur API abrufen
  • Datensatz anlegen oder überschreiben (2 Varianten)
  • Datensatz abfragen
  • Datensatz löschen
  • Liste der Datensätze abfragen

Reporting-API

Um Reportingdaten abzurufen verwenden Sie bitte die Reporting-API, siehe Hilfe -> Statistiken -> Reporting-API.

API-Informationen abrufen

Um Informationen über eine der Schnittstellen abzurufen rufen Sie die URL per HTTP GET zusammen mit dem Parameter apicall=1 auf. Es erscheint eine HTML-Datei mit Informationen zur jeweiligen Schnittstelle. 

Daten an die API senden (Variante 1)

Um Daten an eine Schnittstelle zu senden verwenden Sie immer HTTP POST sowie den Parameter apicall=1. Senden Sie immer alle Felder die in der API-Informationsseite aufgelistet werden als POST-Daten an die Schnittstelle. Achten Sie dabei auf das jeweilige Format sowie den Datentyp. Setzen Sie den Parameter intID auf die ID die Sie ändern möchten oder auf -1 um einen neuen Datensatz zu erzeugen. In diesem Fall müssen beim Erstellen und Ändern immer alle Datenfelder mitgeschickt werden. Als Rückgabewert erhalten Sie die ID des neu erstellten Datensatzes.

Daten an die API senden (Variante 2)

Um Daten an eine Schnittstelle zu senden verwenden Sie immer HTTP POST sowie den Parameter apicall=1 sowie apitype=json. Außerdem setzen Sie den Parameter apiset=data und apisetid=XXX wobei XXX die Zahl des zu ändernden Datensatzes ist oder -1 sofern ein neuer Datensatz angelegt werden soll. Außerdem übergeben Sie die zu setzenden Daten als als Parameter apisetdata= in Form eines assoziativen JSON Arrays in folgendem Format:

array(
"Feldname" => "Wert",
"Feldname" => "Wert",
...
)

Alle Daten die hierbei nicht übergeben werden, werden mit NULL in die Datenbank eingetragen. Default-Werte der Formulare werden nicht übernommen. Sofern Sie Daten explizit mit NULL überschreiben möchten verwenden Sie bitte die Zeichnkette "\NULL". Als Rückgabewert erhalten Sie von der API die ID des neu erstellten Datensatzes.

Datensatz abfragen

Um einen Datensatz komplett abzufragen senden Sie den Parameter apicall=1 sowie apitype=json an die Schnittstelle. Außerdem senden Sie den Parameter apiget=data und apigetid=x, wobei x die ID des zu liefernden Datensatzes ist. Die API liefert in diesem Fall ein assoziatives JSON Array im Format Feldname=>Wert.

Datensatz löschen

Um einen Datensatz zu löschen senden Sie die ID des zu löschenden Datensatzes an die Schnittstelle. Als Feldname verwenden Sie dabei den ersten Parameter der in der API-Information aufgelistet ist (trägt meist den Namen intID) und setzen dem Namen die Buchstaben "del" voran (demnach meist also "delintID").

Liste der verfügbaren Datensätze abfragen

Um eine Liste aller verfügbaren Datensätze abzufragen senden Sie die Parameter apicall=1, apitype=json sowie apiget=ids an die Schnittstelle. Als Ergebnis erhalten Sie ein nicht-assoziatives JSON Array welches die ID's der verfügbaren Daten enthält.

Neben der reinen Liste an IDs können hiermit auch weitere Daten des Datensatzes abgerufen werden. Hierzu fügen Sie den Parameter &apigetfields=X an, wobei X eine kommegetrennte Liste der Datenbankspalten ist. Beispiel:

&apigetfields=strName,daStart,daEnd

... liefert die Spalten intID sowie strName, daStart und daEnde in einem Array von assoziativen Arrays.

Die Liste der verfügbaren Datensätze können Sie zudem mit dem Parameter apifilter filtern. Als Wert erwartet der Filter ein JSON-decodiertes Array von Name-Wert-Paaren. Beispiel (PHP):

$url .= '&apifilter='.urlencode(json_encode(array('U_intID'=>51)));

 (Filtert die Liste sodass nur Datensätze ausgegeben werden deren Wert U_intID gleich 51 sind.)

Zusätzlich lässt sich je Feld innerhalb des Arrays die Vergleichsmethode angeben indem dem Feldnamen das Wort "_COMPARE" angehängt wird. Beispiel:

$url .= '&apifilter='.urlencode(json_encode(array('U_intID'=>51,'U_intID_COMPARE'=>3)));

Als Wert wird hierbei einer der folgenden Werte übergeben:

Wert Bedeutung
0 Verglichen wird mit = (gleich
1 Verglichen wird mit LIKE (Stringvergleich für "beinhaltet")
2 Verglichen wird mit > (größer als)
3 Verglichen wird mit < (kleiner als)
4 Verglichen wird mit <> (ungleich)
5 Verglichen wird mit >= (größer gleich)
6 Verglichen wird mit <= (kleiner gleich)
7 Verglichen wird mit IN (Liste aus Werten; kommagetrennt)

Obiger Beispielfilter liefert demnach alle Einträge deren Publisher-ID kleiner als 51 ist.

Ebenso lässt sich die Reihenfolge der Datensätze manipulieren:

$url .= '&apiorder='.urlencode(json_encode(array('strURL'=>'ASC','isAktiv'=>'DESC')));

Auch lässt sich optional die Anzahl begrenzen:

$url .= '&apilimitcount=3';

Optional dazu auch der Offset bestimmen (Startwert der Abfrage):

$url .= '&apilimitoffset=3';

Bei einer Abfrage mit begrenzten Datensätzen lässt sich zudem die Gesamtzahl der Datensätze abfragen:

$url .= '&apirowcount=1'

... fügt dem Ergebnis die Anzahl an Zeilen an, die ohne Limit verfügbar sind (vgl. SQL_CALC_FOUND_ROWS in MySQL)

Beispielumsetzung PHP

Der folgende PHP-Code zeigt beispielhaft das Anlegen eines neuen Publishers mittels API. Die Vorlage kann entsprechend auch auf andere Sachverhalte umgestellt werden.

<?

$api_host = '127.0.0.1'; //e.g. meinname1.adspirit.de
$api_pass = 'xyz';

 include_once('/system/HTTP_Request/Request.php'); //PEAR HTTP-REQUEST LIBRARY
$data = array( //the data to set; to know the fieldnames call http://[$api_host]/control/user_edit.php?apicall=1 with HTTP GET
'strName' => 'Winkler',
'strVorname' => 'Jan',
'strTel' => '+49(0)30-484849-505',
'strLogin' => 'janwinkler',
'strPass' => 'test1234',
'intStatus' => 1
);

    $req = new HTTP_Request('http://'.$api_host.'/control/user_edit.php'); //url to send the request; e.g. /control/user_edit.php for publisher, /control/webseiten_edit.php for websites and so on
    $req->setMethod(HTTP_REQUEST_METHOD_POST);
    $req->addPostData('apicall', '1');
    $req->addPostData('kname', 'admin'); //username for API user
    $req->addPostData('kpass', $api_pass); //password for API user
    //A: this way you only set the data, no errorhandling will be made, no default-values will be inserted
    /*
    $req->addPostData('apitype', 'json');
    $req->addPostData('apiset', 'data');
    $req->addPostData('apisetid', '-1'); //apisetid=-1 => create new; apisetid>0 => change exitsing id
    $req->addPostData('apisetdata', json_encode($data));
    */
    //B: this way you set the data, errorhandling will be made, all values which are not set will be inserted with default-values; this is the better way
    $keys = array_keys($data);
    for($i=0;$i<count($keys);$i++)
    {
     $req->addPostData($keys[$i], $data[$keys[$i]]);
    }
    $req->addPostData('intID', '-1'); //intID=-1 => create new; intID>0 => change exitsing id
    //send the request
    $req->sendRequest();
    //get the result
    echo '<pre>';
    var_dump($req->getResponseBody()); // will output the ID of the new created element
?>

 

Spezielle APIs

Neben den Formular-APIs gibt es folgende spezielle APIs:

Upload-API

Zum Upload von Werbemitteln auf die Imageserver verwenden Sie bitte
/control/api_upload.php
Nähere Informationen finden Sie in der Beispieldatei unter /control/api_upload_test.html

Buchungs-API

Um Buchungen anzulegen verwenden Sie bitte

/control/api_booking.php

Diese erwartet folgende Parameter um eine Buchung bzw einen Ausschluss anzulegen:

Parameter Bedeutung
&type=0/1/2/3/4/5/6 0=Buchung hinzufügen, 1=Buchung löschen, 2=Ausschluss hinzufügen, 3=Ausschluss löschen, 4=Liste der aktuell laufenden Kampagnen für eine Webseite/Werbefläche ausgeben, 5=Liste für die auf einer Werbefläche aktuell gebuchten Werbemittel einer Kampagne ausgeben, 6=Liste der Buchungen und Ausschlüsse ausgeben 
&kid= Kampagnen-ID
&wmid= Werbemittel-ID
&cid= Channel-ID
&wsid= Webseiten-ID
&pid= Werbeflächen-ID
&sid= Sub-ID
&prio= Priorität
&order= Reihenfolge
&weight= Anteil

Beispiele:

/control/api_booking.php?type=0&cid=3&kid=4 Bucht die Kampagne 4 auf den Channel 3 und verwendet dabei alle Werbemittel sowie die Standard-Einstellungen für Priorität und Reihenfolge sowie Anteil=1.
/control/api_booking.php?type=0&wsid=3&pid=4&kid=5&wmid=6 Bucht die Kampagne 5 mit dem Werbemittel 6 auf die Werbefläche 4 der Webseite 3.
/control/api_booking.php?type=4&wsid=3 Gibt eine Liste aller auf Webseite 3 aktuell laufenden Kampagnen zurück.
/control/api_booking.php?type=4&pid=3 Gibt eine Liste aller auf Werbefläche 3 aktuell laufenden Kampagnen zurück.
/control/api_booking.php?type=5&pid=3&kid=23 Gibt eine Liste aller aktuell von Kampagne 23 auf Werbefläche 3 laufenden Werbemittel zurück.
/control/api_booking.php?type=6&pid=3 Gibt eine Liste aller Buchungen und Ausschlüsse die sich explizit auf Werbefläche 3 beziehen (implizite Buchungen/Ausschlüsse etwa über Webseiten/Channel werden nicht erfasst).
/control/api_booking.php?type=6&cid=0&kid=5 Gibt eine Liste aller Buchungen und Ausschlüsse die sich explizit auf Channel 0 ("RON") beziehen und die Kampagne 5 betreffen. (implizite Buchungen/Ausschlüsse etwa über Webseiten/Channel werden nicht erfasst).

Blocklist-API

Mittels der Blocklist-API können berechtigte Publisher Kampagnen, Kampagnenkategorien und Advertiser von ihren Webseiten ausschließen. Dazu verwenden Sie folgende URLs: 

  • /user/api_blocklist.php - Liefert eine Liste der zu blockierenden Advertiser/Kategorien
  • /user/api_blocklist.php?do=addcategory&id=CATEGORYID&wsid=WEBSITEID - Fügt eine Kategorie der Blocklist der Webseite hinzu
  • /user/api_blocklist.php?do=dropcategory&id=CATEGORYID&wsid=WEBSITEID - Entfernt eine Kategorie von der Blocklist einer Webseite
  • /user/api_blocklist.php?do=addadvertiser&id=ADVERTISERID&wsid=WEBSITEID - Fügt einen Advertiser der Blocklist der Webseite hinzu
  • /user/api_blocklist.php?do=removeadvertiser&id=ADVERTISERID&wsid=WEBSITEID - Entfernt einen Advertiser von der Blocklist einer Webseite
  • /user/api_categorylist.php - Liefert eine Liste aller vorhandenen Kategorien
  • /user/api_advertiserlist.php - Liefert eine Liste aller vorhandenen Advertisernamen
  • /user/api_campaignlist.php - Liefert eine Liste der aktuell auf den Webseiten laufenden Kampagnen
  • /user/api_campaignlist.php?do=blockcampaign&id=CAMPAIGNID&pid=PLACEMENTID - Entfernt eine gebuchte Kampagne von der Werbefläche

Channel-API

Mit der Channel-API können Sie Webseiten/Werbeflächen einem Channel zuordnen. Rufen Sie dafür die folgende URL auf:

/control/api_channel.php?cid=[Channel-ID]&wsid=[Website-ID]&pid=[Werbeflächen-ID]&type=[Aktion]

 

Der Parameter &type= kann dabei folgende Werte annehmen:

0 = eine Website/Werbefläche zu einem Channel hinzufügen

1 = eine Website/Werbefläche von einem Channel entfernen

2 = gibt eine Liste aller Channel aus, die mit einer Website/Werbefläche verknüpft sind (Parameter &cid= entfällt hier)

 

Hinweis: Die Werbeflächen-ID ist optional, lassen Sie diesen Parameter leer um die gesamte Webseite zu einem Channel hinzuzufügen/zu entfernen/die Liste zu bekommen.

Forecast-API

Die Daten des täglichen Forecast können via /control/api_forecast.php bezogen werden.

Postleitzahlen-API

Mit /control/api_zipcodes.php können Sie eine Liste der Postleitzahlen für einen bestimmten Umkreis erhalten. Geben Sie dazu die Parameter &country=LÄNDERKÜRZEL (z.B. "DE", "FR" usw) sowie &zip=POSTLEITZAHL (z.B. 10117) und den Umkreis via &range=X (x ist der Umkreis in km) an. Als Ergebnis erhalten Sie eine Liste der Postleitzahlen die im Umkreis von x Kilometern um die angegebene Postleitzahl herum liegen.

Retargeting-Datenbank-API

Die Daten aus einer der Retargeting-Datenbanken können via /control/api_rt_database_download.php?intID=DATENBANKID bezogen werden (Format CSV, Zeichensatz UTF-8). Zusätzlich sind folgende Parameter möglich:

Parameter Bedeutung
&separator= Trennzeichnen mit dem die Spalten getrennt werden sollen. (Default: "," )
&fixzeroX=Y Gibt an, dass in Spalte Nummer X (erste Spalte ist 0, zweite ist 1 usw) die dort befindliche Zahl auf  Y Stellen mit Nullen aufgefüllt werden soll. Beispiel &fixzero3=5 ändert in Spalte 4 einen Wert "123" in "00123" (sinnvoll z.B. bei Postleitzahlen)
&clk=X
&wmid=
&pid=
Gibt an, dass die in Spalte X befindliche URL in eine Klick-URL umgewandelt werden soll. Hierzu ist es notwendig, dass auch die Parameter &wmid= (Werbemittel-ID) und &pid= (Werbeflächen-ID) angegeben werden.
&urlenc=X Gibt an, dass die Klick-URL (siehe oben) X mal url-codiert werden soll. (Default: 0)
&urlenctarg=X Gibt an, dass innerhalb der Klick-URL das Ziel X mal url-codiert werden soll. (Default: 1)

Übersichtsdaten-API

Die Übersichtsdaten der Advertiser (Kampagnen) und Publisher (Webseiten) lassen sich ebenfalls via API als XML-Datensatz exportieren:

/client/api_overview.php - liefert eine XML-Liste der aktuell laufenden Kampagnen des Advertisers

/user/api_overview.php - liefert für die Webseiten des Publishers die aktuellen Eckdaten

Abrechnungsdaten-API

Zur Übersicht der gestellten Rechnungen und Gutschriften können die folgenden zwei APIs benutzt werden:

/control/api_billing.php?from=yyyy-mm-dd&to=yyyy-mm-dd - liefert eine Liste der in diesem Zeitraum vorhandenen Rechnungen, Gutschriften und Abrechnungsinformationen

/control/api_accounting.php?uid=X bzw ...?mid=X  - liefert das AdServerkonto des Publishers/Advertisers

Publisherkonto-API

Um Zugriff auf das interne Publisherkonto zu erlangen verwenden Sie bitte:

/control/api_user_konto.php

Diese erwartet folgene Parameter:

Parameter Beschreibung
U_intID ID des Publishers dessen Konto bearbeitet werden soll
action

Typ der Aktion die ausgeführt werden soll:
0 - Kontoliste abrufen. Liefert eine XML-Datei mit allen Einträgen des Nutzerkontos
1 - Neuen Eintrag hinzufügen
2 - Eintrag updaten
3 - Eintrag löschen

intID ID des Eintrags der geupdated oder gelöscht werden soll
K_intID ID der Kampagne der dieser Eintrag zugewiesen werden soll
daDate Datum des Eintrags
intMonth Monat (1-12) auf den sich der Eintrag bezieht
intYear Jahr (2000-2100) auf den sich der Eintrag bezieht
intType Typ des Eintrags:
0 - Kontonotiz
1 - Gutschriftbetrag überwiesen
2 - Extrazahlung
3 - Strafrabatt
4 - Fremdrechnungszahlung
floatBetrag Betrag (muss 0.00 sein bei intType = 1)
strDescr Beschreibungstext

Advertiserkonto-API

Um Zugriff auf das interne Advertiserkonto zu erlangen verwenden Sie bitte:

/control/api_werbende_konto.php

Diese erwartet folgene Parameter:

Parameter Beschreibung
M_intID ID des Advertisers dessen Konto bearbeitet werden soll
action

Typ der Aktion die ausgeführt werden soll:
0 - Kontoliste abrufen. Liefert eine XML-Datei mit allen Einträgen des Nutzerkontos
1 - Neuen Eintrag hinzufügen
2 - Eintrag updaten
3 - Eintrag löschen

intID ID des Eintrags der geupdated oder gelöscht werden soll
daDate Datum des Eintrags
floatBetrag Betrag
strDescr Beschreibungstext

Action-Warteschlange

Die Action-Warteschlange kann mit der API /control/api_track_open.php als CSV exportiert werden. Als Parameter sind möglich:

Parameter  Beschreibung 
kid= (optional) ID der Kampagne
wsid= (optional) ID der Webseite
from=YYYY-MM-DD Startdatum 
to=YYYY-MM-DD Enddatum

Darüber hinaus können die Actions der Warteschlange mit der API /control/api_track_update.php gutgeschrieben bzw storniert werden. Folgende Parameter sind dabei möglich:

Parameter  Beschreibung 
 id= ID der Action aus der Warteschlage 
 type= 1=Gutschreiben, 2=Stornieren
 reason= (optional) Nur bei Storno: 
0: Ohne Grund
1: Doublette
2: Ungültige Aktion
3: Negative Adresse/Bonität
4: Bestellung nicht bezahlt
5: Kunde hat storniert
6: Falsche Kundenangaben
7: Kein Vertrag
8: Andere Gründe
9: Testbestellung

Die API gibt ein JSON-Resultat mit der neuen ID der Action in der Gutschriftliste bzw Stornoliste zurück.

Geo-API

Mittels der Geo-API /control/api_geo.php kann das Geotargeting, ISP-Targeting und IP-Targeting für eine Kampagne oder ein Werbemittel eingestellt werden. Folgende Parameter stehen zur Verfügung:

Parameter  Beschreibung 
 type=

Aufgabentyp:
0=Liste der Länder abfragen
1=Liste der Regionen abfragen
2=Liste der Location-IDs abfragen
3=Liste der ISPs abfragen
4=Targetingeinstellungen für Kampagne/Werbemittel abfragen
5=Geotargeting setzen
6=ISP-Targeting setzen
7=IP-Targeting setzen

 cc= (nur bei type=1/2) Filter für Land
 reg= (nur bei type=2) Filter für Region
 kid= / wmid= (nur bei type=4/5/6/7) ID der zu setzenden Kampagne/Werbemittel
 countries[]= (nur bei type=5/6) Array der zu setzenden Länder
 regions[]= (nur bei type=5) Array der zu setzenden Regionen (Schreibweise: Ländercode + '_' + Region-ID)
 locations[]= (nur bei type=5) Array der zu setzenden Location-IDs
 ispids[]= (nur bei type=6) Array der zu setzenden ISP-IDs
 ips[]= / ips2[]= (nur bei type=7) Arrays der Start- und End-IPs


Liste der API-URLs

Folgende URLs unterstützen aktuell den Zugriff via API:

control\abrechnung_zahlungsziel.php
control\add_campaign_to_invoice.php
control\admins_edit.php
control\admins_edit2.php
control\advertiser_talk_edit.php
control\affiliate.php
control\agenturen_cust_chn.php
control\agenturen_cust_format.php
control\agenturen_edit.php
control\agenturen_planer_function.php
control\agenturen_planer_talk_edit.php
control\agenturen_typen.php
control\akquise_edit.php
control\akquise_grund.php
control\akquise_kunden_info_edit.php
control\akquise_kunden_properties_edit.php
control\akquise_talk_edit.php
control\banner_gif_config.php
control\chn_edit.php
control\email_texts.php
control\goals_edit.php
control\groups_edit.php
control\iash_edit.php
control\import_edit.php
control\insert_revenue_forecast.php
control\kampagnen_cookie_edit.php
control\kampagnen_edit.php
control\kampagnen_kat.php
control\kamp_track_edit.php
control\keywords_edit.php
control\mandant.php
control\mediaplan_adsizes.php
control\mediaplan_booking_edit.php
control\mediaplan_edit.php
control\mediaplan_flight_edit.php
control\mediaplan_offer_edit.php
control\mediaplan_offer_invite.php
control\notifications_edit.php
control\planung_angebot_edit.php
control\planung_aufgabe_edit.php
control\pool_edit.php
control\port_print_designs.php
control\port_print_edit.php
control\port_print_project_edit.php
control\port_user_edit.php
control\reporting.php
control\reportingvorlage.php
control\rtb_sellermatching.php
control\rtb_usermatch_edit.php
control\rt_database_edit.php
control\rt_database_edit_element.php
control\rt_piggy_edit.php
control\rt_redirect_edit.php
control\seitenakquise_kat.php
control\seitenakquise_status.php
control\set_campaign_in_invoice.php
control\templates_edit.php
control\trackingweiche_edit.php
control\trackingweiche_itm_edit.php
control\usermatching_edit.php
control\user_aliases.php
control\user_edit.php
control\user_nomail.php
control\user_typen.php
control\webseiten_adsizes.php
control\webseiten_edit.php
control\webseiten_orgs.php
control\webseiten_share.php
control\webseiten_typen.php
control\webseite_talk_edit.php
control\werbemittel_new_banner.php
control\werbemittel_new_dhtml.php
control\werbemittel_new_ga.php
control\werbemittel_new_html.php
control\werbemittel_new_mobile_banner.php
control\werbemittel_new_mobile_ga.php
control\werbemittel_new_mobile_html.php
control\werbemittel_new_mobile_video.php
control\werbemittel_new_pop.php
control\werbemittel_new_rtb.php
control\werbemittel_new_video.php
control\werbemittel_video_design.php
control\werbende_address.php
control\werbende_edit.php
control\werbende_subaccount.php
control\werbende_subaccount_attach.php
control\workflowsetup_edit.php
control\workflowsetup_itm_edit.php
control\workflow_edit.php