on 10 June 2013 02:38 PM
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.
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.
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.
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.
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/
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:
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.
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:
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.