The AdServer offers the possibility to automatically send data to the server via an API.
This allows you to create new data records or change existing data records.
IMPORTANT: Access via API can lead to serious errors in the settings and operation of the AdServer. If you want to use the API, it is therefore strongly recommended to coordinate this with your respective technical contact.
API access
Access to the API respectively via the URL that you use in AdSpirit Control of the form. To create such a campaign via API go quickly from her AdSpirit Control, edit them on the campaign and can be of your browser the URL of the form show (in this case http://[AdServer-URL]/control/kampagnen_edit.php); see also below list of API URLs. In addition, there are some specific APIs cover the individual functions.
All URLs can be accessed via HTTP GET and POST.
authentication
The parameters can kname (username) and kpass (password) or kmd (session key) can be used for authentication.
To create a session key, please use the API /control/api_kmd.php and pass Username + Password (kname/kpass) and type=X where X is the type of login (0=control, 1=Publisher, 2=Advertiser). Please note that a generated through this API key has an expiration date of 1 year.
Beispiel:
http://xxxx/control/api_kmd.php?kname=XXXX&kpass=XXXX&type=0
Result Sessionkey:
|
Notice:
|
API functions
Each API provides several functions:
- obtain information about the API
- creating a data record or overwrite (2 variants)
- query data
- delete dataset
- Check list of records
Reporting API
To retrieve reporting data, please use the Reporting API, see REPORTING API
Retrieving API Information
To get information about one of the interfaces call the URL via HTTP GET together with the parameter apicall=1. You will see a HTML file containing information on each interface.
send data to the API (version 1)
To send data to an interface always use HTTP POST and the parameter apicall=1. Always send all the fields that are listed in the API information page as POST data to the interface. Pay attention to that format and the data type. Set the parameter IntID to the ID you want to change or create to -1 to a new record. In this case, getting all the data fields are sent when creating and modifying. The return value to get the ID of the record newly created.
send data to the API (version 2)
To send data to an interface always use HTTP POST and the parameter apicall=1 and json=apitype. Also, set the parameter apiset=data and apisetid=XXX where XXX is the number to be changed record or -1 if a new record is to be created. You pass addition to passing data as a parameter apisetdata=in the form of an associative array JSON in the following format:
array(
"Field Name" => "value",
"Field Name" => "value",
...
)
If you create a record, all data that is not transferred to the API will be entered into the database with NULL. Default values of the forms are not transferred. If you change a data record, only data that is sent to the API will be overwritten.
If you want to overwrite data explicitly with NULL, please use the character string "\NULL". The API will return the ID of the newly created record.
query data
To complete query a record post parameter apicall=1 and apitype=json to the interface. You also send the parameters apiget=data and apigetid=x where x is the ID of the data to be provided is set. The API returns an associative array JSON in the format field name=>value in this case.
delete dataset
To delete a record send the ID of the deleted record to the interface. this field name using the first parameter is listed in the API information (usually bears the name IntID) and insert the name of the letter "del" ahead (thus usually so "delintID").
Check list of available records
To retrieve a list of all available records send the parameters apicall = 1, apitype = json and apiget = ids to the interface. The result is a non-associative JSON array containing the IDs of the available data.
Besides the pure list of IDs also record data hereby can be retrieved. To do this, add the parameter & apigetfields = X at, where X is a come-separated list of database columns. Example:
&apigetfields=strName,daStart,daEnd
... returns the column IntID and strName, daStart and daEnde in an array of associative arrays.
The list of available records, you can also filter apifilter with the parameter. The value of the filter expects a JSON decoded array of name-value pairs. Example (PHP):
$url .= '&apifilter='.urlencode(json_encode(array('U_intID'=>51)));
(Filters the list so that only output records whose value U_intID are equal. 51)
In addition, the comparison method can be indicated by the word "_COMPARE" is appended to the field name for each field within the array. Example:
$url .= '&apifilter='.urlencode(json_encode(array('U_intID'=>51,'U_intID_COMPARE'=>3)));
one of the following is hereby passed by value:
| value | meaning |
| 0 | is compared with = (equal to |
| 1 | is compared with LIKE (string comparison for "includes") |
| 2 | is compared with> (greater than) |
| 3 | Is compared with less than (<) |
| 4 | is compared with <> (not equal) |
| 5 | is compared with> = (greater than or equal to) |
| 6 | is compared with <= (less than or equal) |
| 7 | is compared with IN (list of values, separated by commas) |
Accordingly, the above example filter returns all entries whose publisher ID is smaller than 51st
Likewise, the order of the records can be manipulated:
$url .= '&apiorder='.urlencode(json_encode(array('strURL'=>'ASC','isAktiv'=>'DESC')));
The number can optionally limit:
$url .= '&apilimitcount=3';
Optionally, also the offset to determine (start value of the query):
$url .= '&apilimitoffset=3';
Based on a survey with limited data sets is also the total number of records can be queried::
$url .= '&apirowcount=1'
... (SQL_CALC_FOUND_ROWS see. In MySQL) adds to the result, the number of lines, which are available without limit
Example implementation PHP
The following PHP code shows an example of the application of a new Publishers means of API. The template can be changed according to other matters.
<?
$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
?>
specific APIs
Apart from the form APIs, the following special APIs
Upload API
To upload advertising material to the Image Server, please use /control/api_upload.php
more information, see the sample file below /control/api_upload_test.html
Booking API
To create bookings please use
/control/api_booking.php
This expects the following parameters to make a booking or to create an exclusion:
| parameter | meaning |
| & Type = 0/1/2/3/4/5/6 | Add 0 = booking, 1 = Delete booking, add 2 = exclusion, remove 3 = no, 4 = list of currently running campaigns for a website / Advertising spend, spend 5 = list for on an advertising space currently booked advertising media campaign, 6 = list of reservations and exclusions to spend |
| &kid= | Campaign ID |
| &wmid= | Advertising media ID |
| &cid= | Channel ID |
| &wsid= | Website ID |
| &pid= | Billboards ID |
| &sid= | Sub-ID |
| &prio= | priority |
| &order= | sequence |
| &weight= | proportion of |
Examples:
| /control/api_booking.php?type=0&cid=3&kid=4 | Bay Campaign 4 on Channel 3, while using all advertising materials as well as the default settings for priority and order and proportion = 1st |
| /control/api_booking.php?type=0&wsid=3&pid=4&kid=5&wmid=6 | Bay Campaign 5 with the advertising material 6 on the advertising area 4 of the website. 3 |
| /control/api_booking.php?type=4&wsid=3 | Returns a list of all the Web Page 3 currently running campaigns. |
| /control/api_booking.php?type=4&pid=3 | Returns a list of all ad space on 3 currently running campaigns. |
| /control/api_booking.php?type=5&pid=3&kid=23 | Returns a list of all currently running campaign 23 Advertising space 3 advertising. |
| /control/api_booking.php?type=6&pid=3 | Returns a list of all bookings and exclusions that relate explicitly to advertising space 3 (be implicit Reservations / exclusions as via websites / Channel not recorded). |
| /control/api_booking.php?type=6&cid=0&kid=5 | Returns a list of all bookings and exclusions which are explicitly on Channel 0 ( "RON") and must relate to the campaign. 5 (Implicit Reservations / exclusions as via websites / Channel are not included). |
Block List API
Using the Block List API can exclude legitimate publishers campaigns, campaign categories and advertisers from their websites. To do this use the following URLs:
- /user/api_blocklist.php - Returns a list of blocked Advertiser / Categories
- /user/api_blocklist.php?do=addcategory&id=CATEGORYID&wsid=WEBSITEID - Adds a category of Blocklist the Web page
- /user/api_blocklist.php?do=dropcategory&id=CATEGORYID&wsid=WEBSITEID - Removes a category from the blocklist a website
- /user/api_blocklist.php?do=addadvertiser&id=ADVERTISERID&wsid=WEBSITEID - Adds an advertiser the Blocklist the website
- /user/api_blocklist.php?do=removeadvertiser&id=ADVERTISERID&wsid=WEBSITEID - Removes an advertiser from the blocklist a website
- /user/api_categorylist.php - Returns a list of all categories
- /user/api_advertiserlist.php - Returns a list of all Advertisernamen
- /user/api_campaignlist.php - Provides a list of currently running campaigns on the websites
- /user/api_campaignlist.php?do=blockcampaign&id=CAMPAIGNID&pid=PLACEMENTID - Removes a booked campaign by the advertising space
Channel API
With the Channel API, you can assign websites / ad panels a channel. Call it the following URL:
/control/api_channel.php?cid=[Channel-ID]&wsid=[Website-ID]&pid=[Werbeflächen-ID]&type=[Aktion]
The Parameter &type= can take following values:
0 = a site / advertising space Add to Channel
1 = a site / ad space from a channel Remove
2 = displays a list of all the channel associated with a website / advertising space (parameter & cid = not applicable here)
Note: The advertising space ID is optional, you leave this parameter blank to the entire Web page add to a channel / remove / get the list.
Forecast API
The data of the daily forecast can be obtained via /control/api_forecast.php.
ZIP-API
With /control/api_zipcodes.php You can get a list of ZIP codes for a given radius. To do this, the parameters country = country code (eg "EN", "FR", etc) and & zip = ZIP CODE (eg 10117) and the perimeter via & range = X (x is the radius in km) to. As a result you get a list of postal codes that are within x kilometers around the postcode given around.
Retargeting database API
The data from one of the retargeting databases are available via /control/api_rt_database_download.php?intID=DATENBANKID (CSV format, UTF-8). In addition, the following parameters are possible:
| Parameter | Bedeutung |
| &separator= | Separating drawing with which the columns are to be separated. (Default: "") |
| &fixzeroX=Y | Indicates that in column number X (first column is 0 second is 1, etc) the number located there to be filled up to Y points with zeros. in column 4 for example & fixzero3 = 5 changes a value "123" in "00123" (useful for example in ZIP) |
| &clk=X &wmid= &pid= |
Indicates that the URL contained in column X to be converted into a click-through URL. For this it is necessary that the parameters & WMID = (advertising media ID) and & pid = (billboards ID) can be specified. |
| &urlenc=X | Indicates that the click URL (see above) X times url-encoded to be. (Default: 0) |
| &urlenctarg=X | Indicates that the target X to be url-encoded times within the click-through URL. (Default: 1) |
Overview Data API
The summary data of the Advertiser (campaigns) and publishers (websites) can be also exported via API as XML data:
/client/api_overview.php - provides an XML list of ongoing campaigns of the Advertiser
/user/api_overview.php - supplies for the website of the publisher's benchmark data
Billing Data API
To Overview of questions invoices and credit the following two APIs can be used:
/control/api_billing.php?from=yyyy-mm-dd&to=yyyy-mm-dd - provides a list of the available during this period invoices, credit and billing information
/control/api_accounting.php?uid=X or ... mid = X - delivers the AdServerkonto publisher / Advertisers
Publisher Account API
To gain access to the internal publisher account, please use:
/control/api_user_konto.php
This expects the following parameters:
| parameter | description |
| U_intID | ID of the publisher's account to be edited |
| action |
Type of action to be performed: |
| IntID | ID of the entry is to be updated or deleted |
| K_intID | to be assigned ID of the campaign this entry |
| daDate | Date of entry |
| intMonth | Month (1-12) to which the entry refers |
| intYear | Years (2000-2100) the entry refers to |
| intType | Entry type: 0 - account Note 1 - credit amount transferred 2 - Extra Payment 3 - Use criminal 4 - foreign bill payment |
| floatBetrag | (Must be at 0:00 INTTYPE = 1) Amount |
| strDescr | Description text |
Advertiserkonto API
To gain access to the internal Advertiserkonto please use:
/control/api_werbende_konto.php
This expected folgene parameters:
| parameter | description |
| M_intID | ID of the Advertiser's account to be edited |
| action |
Type of action to be performed: |
| IntID | ID of the entry is to be updated or deleted |
| daDate | Date of entry |
| floatbetrag | amount |
| strDescr | Description text |
Action Queue
The action queue can be exported with the API /control/api_track_open.php as CSV. As parameters are possible:
| parameter | description |
| kid= | (Optional) ID of the campaign |
| wsid= | (Optional) ID of the website |
| from=YYYY-MM-DD | start date |
| to=YYYY-MM-DD | end date |
In addition, the actions of the queue with the API /control/api_track_update.php can be credited or canceled. The following parameters are possible:
| parameter | description |
| id = | ID of the action from the queue |
| type = | 1 = crediting, 2 = Cancel |
| reason = | (optional) Only for cancellation: 0: Without reason 1: Doublette 2: Invalid action 3: Negative address / credit 4: Order not paid 5: customer has canceled 6: Incorrect customer specifications 7: No contract 8: Other reasons 9: Test Order |
The API returns a JSON result with the new ID of the action in the credit list or cancellation list back.
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 | description |
| type= |
Task Type: |
| cc= | (Only for type = 1/2) filter for Land |
| reg= | (Only for type = 2) filter for region |
| kid= / wmid= | (Only for type = 4/5/6/7) of the ID to be set campaign / advertising material |
| countries[]= | (Only for type = 5/6) array of countries to be set |
| regions[]= | (Only for type = 5) array of regions to be set (notation: country code + '_' + region ID) |
| locations[]= | (Only for type = 5) of the array to be set Location IDs |
| ispids[]= | (Only for type = 6) of the array to be set ISP-IDs |
| ips[]= / ips2[]= | (Only for type = 7) array of start and end IPs |
List of API URLs
The following URLs currently support access 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