Epom Ad Server includes the functionality to serve ads via Application Program Interface (API).

To find out your network-specific parameters, switch to the API tab of the Invocation Codes window:

API placement

In order to request an ad from a certain Placement you should send the parameters listed below within HTTP GET or POST request to the Request URL. Available response formats are: HTML(default), XML, JSON and JSONP.

Parameter Description Sample response Mandatory
key Unique Identifier of the Placement 92d6f4e52026a25dfce11cbda35e6260 true
clientIp Client's IP address 112.12.23.33 true
clientUa Client's User-Agent Android (Linux; U; Android 2.2.1; in-id; GT-S5570)
AppleWebKit/528.5+ (KHTML) Version/3.1.2
false
requestUrl Client's Request URL http://foo.bar/foo/bar true
format Response format: HTML (default), JSONP, JSON, XML, or xml-bids. JSONP false
callback Name of the JSONP callback function. callback123213 Only for JSONP response format.
tz Client's time zone -1; 2; 5.5 false
latitude Client's latitude 3.13192 false
longitude Client's longitude 101.684059 false
didsha1 Device ID in SHA1 hash format hash value false
didmd5 Device ID in MD5 hash format hash value false
dpidsha1 Android ID or UDID in SHA1 hash format hash value false
dpidmd5 Android ID or UDID for iOS in MD5 hash format hash value false
model Device model iPhone false
make Device vendor Apple false
devicetype Device type (1 - Mobile, 2 - PC, 3 - Connected TV) 1 false
clientOs Client's Operation System Chrome OS, FreeBSD, BlackBerry, Solaris, Palm OS, Windows, Linux, Symbian, Android, Unspecified, Bada, MeeGo, Windows Phone, XrossMediaBar (XMB), Mac OS X, iOS, J2ME false
osv Client's OS version 3.1.2 false
no_impressions_report No-impressions data per banner {bannerId}|{count}|{bannerId}|{count}|... false

note Quick Start Guide
Note!

It is also possible to pass Custom Parameters via API requests.


Example

Lets assume that it is needed to request an ad in the XML format. To accomplish that:

  1. Copy the Request URL from the API tab of the Invocation Codes pane. For this example it will be:
  2. http://n101.epom.com/ads-api-v3
  3. Add the placeholders for parameters to the Request URL:
  4. http://n101.epom.com/ads-api-v3?key=&format=
  5. Copy and paste the corresponding values from the API tab of the Invocation Codes pane:
  6. http://n101.epom.com/ads-api-v3?key=6d83a03ab653bbe2d51d05c95fad88a5&format=XML
  7. Paste the Request URL with parameters into the address field of your Web Browser and press Enter.

This should return you the information regarding the Banners linked to the Placement in question in the XML format:

200 OK

It consists of the following sections:

  • creative - path to the Banner creative.
  • beacon - Impression tracking URL.
  • click - Click tracking URL.
  • code - Banner source code.

To check if there is a Banner that can be served, open the Developer tools in your Web Browser and switch to the Network tab. The response code (Status) should be 200 OK:

200 OK

For another banner types, the responses would be:

HTML response sample:

<a href="http://foo.bar/landing" target="_blank"> <img border="0" alt="foo.bar" src="http://foo.bar/img.png" width="300" height="50"></a>

JSONP response sample:

jQuery172021720809857884849_1337079958141({"code":"<a href=\"http:\/\/foo.bar\/landing\" target=\"_blank\">\n <img border=\"0\" alt=\"foo.bar\" src=\"http:\/\/foo.bar\/img.png\" width=\"300\" height=\"50\">\n <\/a>"});

JSON response sample:

{ "success":true,
"creative":"http://path.to.creative/320x50.gif",
"click":"http://landing.url/landing",
"beacon":"http://impression.beacon/impression.gif",
"code":"<a href=\"http://landing.url/landing\" target=\"_blank\"><img border=\"0\" alt=\"\" src=\"http://path.to.creative/320x50.gif\" width=\"320\" height=\"50\"></a><img src=\"http://impression.beacon/impression.gif\"/>" }

When there is no Banner that can be displayed, the response code would be the same (200 OK), but a No-impression beacon will be served instead of banner markup.

HTML No-impression response sample:

<script type="text/javascript">
new Image().src = "http://impression.beacon/no_impression.gif";
</script>

JSONP No-impression response sample:

jQuery172021720809857884849_1337079958141({
"code":"<script type=\"text\/javascript\">
new Image().src = "http:\/\/impression.beacon\/no_impression.gif\"
;<\/script>"
});

JSON No-impression response sample:

{"success":false,
"code":"<script type="text/javascript">
new Image().src = http://impression.beacon/no_impression.gif";
</script>"}

XML No-impression response sample:

<response><success>false</success><code><script type="text/javascript">new
Image().src = "http://impression.beacon/no_impression.gif";</script></code></response>

Custom Parameters in API request

Epom Ad Server provides an option to pass Custom Parameters in API request. The general syntax for the parameters should be cp.[parameter-name]=[parameter-value]. For example: 'cp.price=42' or 'cp.product=shoes'. The parameter separator is '&'.

So, to pass the aforementioned parameters, the API request should be:

http://n101adserv.com/ads-api-v3?key=ffebe34d562a894ad4e285ecec1aeee9&cp.price=42&format=json

Need more help?

Should you require any additional help with our solutions, do not hesitate to contact Epom technical support at support@epom.com. Our support managers are dedicated to resolving any issues and providing you with solutions and support if you face difficulties or have questions.