This document is the e-planning ad server API access users' guide. It is aimed at users willing to integrate e-planning adserver with their own proprietary systems.
Before reading this document it is advisable to familiarize with e-planning adserver tool and its Users' Guide.
This API allows basic operations on objects managed by e-planning ad server, such as campaigns, advertisers, zones, etc. The potential operations could involve: creating a new object, listing, modifications, etc. It allows, for instance, a company's internal management system to automatically create campaigns on e-planning adserver and takes control in order to do the billing.
This API works using HTTPS as communication protocol and XML as data exchange format. To access the API, it is mandatory to have an e-planning adserver user login, which can be created on the Users tab.
Objects
The objects available through the API are the same that can be managed through the web interface, with certain limitations. The available attributes are the same as seen on the web interface. Any object created through the API can be instantly seen on the interface and vice versa.
Identifiers
Each object managed through the API has a unique numeric identifier. For example, the campaign identifier is called pauta_id, and its numeric equivalent would be 54435.
Each time an operation must be performed on an API specific object, it is referenced by its identifier.
Operation
Access to the API can be done using any programming language that allows HTTPS requests and parse XML files, e.g.: Java, Perl, C#, C, etc.
Authentication
HTTP basic authentication protocol (Basic Authentication) is used. The API does not use cookies. For each request to the system an user name and password must be included.
Access
To access the API, the base URL must be known first. This depends on which is the e-planning data centre from which the service is provided:
- United States: https://admin.us.e-planning.net/
- Argentina: https://admin.ar.e-planning.net/
- Europe: https://admin.eu.e-planning.net/
| IMPORTANT! From March 2014 API can be accessed through dedicated servers (for USA hosted accounts only) The base URL is then > https://api.us.e-planning.net/admin/ (it changes 'admin' for 'api') |
...
Later on, the relative URL is given for each operation. This must be combined with the base URL to form the complete URL for each operation. For example: If you are using the United States data centre and want to get a campaign listing, the URL is formed as follow:
Base URL:
https://admin.us.e-planning.net/
Operation URL:
/admin/adnet/pub/admin/pautas.html?op=l
Complete URL:
https://admin.us.e-planning.net/admin/adnet/pub/admin/pautas.html?op=l
The access to the interface doesn't require an explicit login. Just make the first request for a particular operation to be logged in the interface. Disconnecting from the interface is needed to end the session.
...
- If you are connected through cookies, the operation is performed by a request to the URL:
...
- If you are NOT connected through cookies, the operation is performed by a request to the URL:
/admin/?relogin=<random>
The element <random> must be replaced by a random number, such as number of seconds for the current day, or another whole number. I.e:
/admin/?relogin=43242341
Some available features
- Ad space listing
- Deleting an ad space
- Zones listing
- Sites listing
- Advertisers listing
- Campaign listing
- Campaign information
- Creating an advertiser
- Creating a campaign
Each operation has an URL and potential parameter.
All parameters must be specified in the URL with the format url-encoded.
Parameters' names must be specified in lower-case, such as shown in the examples.
Operations that consult data are performed by GET method. Operations that modify data are performed by POST method. In this case (POST), the parameters should be sent in the message body (Request Body).
In the listings, filter parameters can be specified; all available objects are displayed by default.