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.
Beispiel:
http://xxxx/control/api_kmd.php?kname=XXXX&kpass=XXXX&type=0
Ergebnis Sessionkey:
 |
Hinweis:
|
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: 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",
...
)
Sofern Sie einen Datensatz erstellen, werden alle Daten die hierbei nicht an die API übergeben werden, mit NULL in die Datenbank eingetragen. Default-Werte der Formulare werden nicht übernommen. Sofern Sie einen Datensatz ändern, werden nur Daten überschrieben die an die API gesendet werden.
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 folgende Parameter:
| Parameter | Beschreibung |
| U_intID | ID des Publishers dessen Konto bearbeitet werden soll |
| action |
Typ der Aktion die ausgeführt werden soll: |
| 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: |
| 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: |
| 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\import_edit.php
control\insert_revenue_forecast.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