Mocean REST API Documentation

From Mocean Mobile Wiki

Jump to: navigation, search

Contents

Overview

The Mocean Mobile platform provides third party developers with the opportunity of retrieving reporting data by programming means. The range of REST API functions described on this page is intended for this purposes.

Each method request will return specific data, choose the method you need from the list, and generate a request according to the method description below.

To gain access to the REST API functionality, you will need your private key. You can request your private key by email TECHSUPPORT@MOCEANMOBILE.COM.

NOTE: THE SYSTEM ALLOWS FOR PROCESSING ONLY 3 REQUESTS FROM THE SAME REST API KEY SIMULTANEOUSLY. IF THERE ARE MORE REQUESTS, THEY ARE KEPT IN THE QUEUE FOR 10 SECONDS WAITING FOR THE RESOURCES. IF THE REQUEST HASN'T BEEN PROCESSED FOR 10 SECONDS, IT WILL BE DROPPED AND THE CLIENT WILL GET AN ERROR MESSAGE AND WILL HAVE TO RETRY THE REQUEST AGAIN.

NOTE: SOME DATA CAN BE CACHED IF THE CURRENT DATE HASN'T BEEN INCLUDED TO THE REQUEST. SO IF YOU WOULD LIKE TO PULL A LARGE AMOUNT OF DATA, PLEASE USE THE CACHED DATA FOR PREVIOUS DAYS AND USE API TO PULL TODAY'S DATA, AS THIS WILL ALLOW FOR FASTER DATA PULLS.

URI Structure

In all cases, the HTTP method used is GET. The general URI structure for all the inventory forecasting API methods is as follows:

http://moceanmobile.com/mocean_rest_server.php?method=api_method_name&param1=param_value&param2=param_value&param3=param_value

api_method_name the name of the API method called. The detailed description of all API methods is given below.
param1, param2, param3 method parameters each preceded by the '&' symbol. The number of parameters depends on a certain method and may vary. You can specify values for available parameters but DO NOT forget to specify those that are required. The list of all the required and available parameters for each method is provided in a method description.

Response Format

All the inventory forecasting REST APIs return HTTP responses in XML. You can find samples of both successful and failure responses in a description for each method.


Add Site API Methods

There are two methods described below that allow adding a publisher site to a network, as well as setting zones within a created site.

addSiteToNetwork()

This function allows you to add a site to your Mocean network.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network the site being added to. To query for specific network IDs, the getNetworkId() API method can be used. required
site_name string The name of the site being added to the network. required
site_url string The URL of the site being added to the network. required
description string A description of the site being added. required
channel_id integer The ID of the channel the site/app content is related to. You can obtain the list of pre-existing content verticals/channels supported by the Mocean Mobile platform in your network under Global Settings navigation. It is allowed to specify some content verticals/channels separating them by commas. required
category_id integer The ID of the category that defines the type of ads allowable to be shown on the site/. You can obtain the list of pre-existing categories supported by the Mocean Mobile platform in your network under Global Settings navigation. It is allowed to specify some categories separating them by commas. required

Request Sample:

Here is an example of HTTP request below. DO NOT forget to replace 'key_value' with your real private key value and specify all other required parameters.

http://www.moceanmobile.com/mocean_rest_server.php?method=addSiteToNetwork&privatekey=key_value&network_id=1&site_name=mocean&site_url=example.com&description=mocean&channel_id=1,4,15&category_id=2

Successful Response:

<xml>
<site>SITE_ID_HERE</site>
</xml>

Failure Response:

<xml>
<error>ERROR_MESSAGE_HERE</error>
</xml>

Possible failures:

Error Message Possible Reason
Could not save! An error occurred while saving site info to database.
Site Already Exists Site with the specified URL already exists in the given network.
Invalid Network ID There is no network with the specified ID owned by the user.
Invalid API Key The ’privatekey’ sent as the input parameter is invalid.

addZoneToSite()

This function can be used for adding a certain zone to the Mocean registered site.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
pubsite_id integer The ID of the publisher site that the zone is being added to. To get the publisher site ID, the getPubsiteId() method can be used. required
zone_name string The name of the zone that is being added.
NOTE: Special characters are allowed but should be url encoded.
required
description string Some text information about the zone. required
zone_type string The type of the zone to be added: 'text', 'banner', 'text&banner' or 'all'. optional
min_cpc float The minimal bid for CPC ads that can be displayed on the zone. optional
min_cpm float The minimal bid for CPM ads that can be displayed on the zone. optional

Example:

Here is an example of HTTP request below. DO NOT forget to replace 'key_value' with your real private key value and specify 'description' of the zone.

Optionally, you can specify 'zone_type', 'min_cpc' and 'min_cpm'. By default, 'min_cpc' and 'min_cpm' ratios will be recorded as 0, 'zone_type' will be set to 'all' (including 'text', 'banner' and 'richmedia').

http://www.moceanmobile.com/mocean_rest_server.php?method=addZoneToSite&privatekey=key_value&pubsite_id=221&zone_name=my_zone&description=my_desc&zone_type=text&min_cpc=0&min_cpm=0

Successful Response:

<xml>
<zone>ZONE_ID_HERE</zone>
</xml>

Failure Response:

<xml>
<error>ERROR_MESSAGE_HERE</error>
</xml>

Possible failures:

Error Message Possible Reason
Could not save zone! An error occurred while saving zone info to database.
Could not find pubsite The site ID provided in input is invalid or the site is not owned by the requesting user.
Invalid API Key The ’privatekey’ sent as the input parameter is invalid.
Improper zone type Value of ’zone_type’ is incorrect.

Get Publisher Info API Methods

Methods described below can be used for getting information about zones/sites/networks created by a publisher.

getNetworkId()

This function returns the id number of the network with the specified subdomain name.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
subdomain string A network subdomain name. optional
deleted integer The flag used for indication deleted networks: set to 1 to retrieve deleted networks; 0 – not deleted networks. optional

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify a certain subdomain and deleted networks indicator to get data for. Otherwise, you will get information on all not deleted networks owned by the requested user.

http://www.moceanmobile.com/mocean_rest_server.php?method=getNetworkId&privatekey=key_value&subdomain=example&deleted=0

Successful Response:

<xml>
<network>
<subdomain>SUBDOMAIN_NAME_HERE</subdomain>
<id>NETWORK_ID_HERE</id>
</network>
</xml>

The response will contain as many <network> elements as there are networks owned by the user. If 'subdomain' specified, the response will contain one <network> element.

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getPubsiteId()

This function returns the Mocean registered id number of the site with the proper URL; it also returns the id number of the network related.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
siteurl string The URL of the site. If not specified, the function returns the data regarding all the publisher’s sites.optional

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify a certain 'siteurl' to get the data for. Otherwise, you will get information regarding all the publisher’s sites.

http://www.moceanmobile.com/mocean_rest_server.php?method=getPubsiteId&privatekey=key_value&siteurl=example.com

Successful Response:

<xml>
<site>
<domain>SITE_DOMAIN_NAME_HERE</domain>
<network_id>NETWORK_ID_HERE</network_id>
<id>SITE_ID_HERE</id>
</site>
</xml>

The response will contain as many <site> elements as there are sites owned by the user. If 'siteurl' specified, the response will contain one <site> element.

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getZoneId()

This function returns information (id number and name) regarding all the zones of a certain site.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
site_id integer The ID of the site to get the zone data for. required

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify 'site_id' you want to get the zone data for.

http://www.moceanmobile.com/mocean_rest_server.php?method=getZoneId&privatekey=key_value&site_id=88

Successful Response:

<xml>
<zone>
<name>ZONE_NAME_HERE</name>
<id>ZONE_ID_HERE</id>
</zone>
</xml>

The response will contain as many <zone> elements as there are zones in the site requested.

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getNetSiteZoneId()

This function returns information in relation to all the sites with the corresponding zones created in each of the user’s networks.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

http://www.moceanmobile.com/mocean_rest_server.php?method=getNetSiteZoneId&privatekey=key_value

Successful Response:

<xml>
<network_site_zone>
<network_name>SUBDOMAIN_HERE</network_name>
<network_id>NETWORK_ID_HERE</network_id>
<site_name>SITE_NAME_HERE</site_name>
<site_url>SITE_URL_HERE</site_url>
<site_id>SITE_ID_HERE</site_id>
<zone_name>ZONE_NAME_HERE</zone_name>
<zone_id>ZONE_ID_NUMBER</zone_id>
</network_site_zone>

</xml>

The response will contain as many <network_site_zone> elements as there are different zones, sites and networks owned by the specified user.

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getLandingPageData()

This function returns information in relation to landing pages (or a certain landing page) created by a certain user.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integer The ID of the network to get the data for. If not specified, the statistics for all the networks of a certain user will be returned. To query for specific network IDs, the getNetworkId() API method can be used. optional
landing_page_id integer The ID of the landing page; if not specified, the function returns information about all the landing pages created by a certain user (in the specified network). optional
date string The start date of the range when a customer was redirected from a certain landing page. The format is YYYY-MM-DD. required
end_date string The end date of the range when a customer was redirected from a certain landing page. The format is YYYY-MM-DD. required

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain date range when the landing pages redirections requested are to be occurred.

Optionally, you can specify a certain network, landing page to get the data for. Otherwise, you will get information regarding all the publisher's landing pages.

http://www.moceanmobile.com/mocean_rest_server.php?method=getLandingPageData&privatekey=key_value&network_id=543&landing_page_id=54&date=2010-05-25&end_date=2010-05-26

Successful Response:

<xml>
<landing_page_data>
<lp_id>LANDING_PAGE_ID_HERE</lp_id>
<lp_name>LANDING_PAGE_NAME_HERE</lp_name>
<url>LANDING_PAGE_URL_HERE</url>
<ip>IP_ADDRESS_HERE</ip>
<ua>USER_AGENT_HERE</ua>
<created>LANDING_PAGE_REDIRECTION_DATE_AND_TIME_HERE</created>
</landing_page_data>
</xml>

The successful response contains the following elements:

  • Landing_page_lead_data:
lp_id - (integer) the ID of the landing page to get the data for.
lp_name - (string) a name of the landing page to get the data for.
url - (string) the url for the user redirection.
ip - (string) ip of the user been redirected.
ua - (string) user agent of the user been redirected.
created - (string) date and time of the user redirection.

The number of the <landing_page_data> elements corresponds to the number of redirections occurred on a certain Mocean Mobile landing page owned by the specified user.

getLandingPageLeadData()

This function returns information in relation to leads that are generated on Mocean Mobile landing pages.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integer The ID of the network to get data for. If not specified, the statistics for all the networks of a certain user will be returned.To query for specific network IDs, the getNetworkId() API method can be used. optional
landing_page_id integer The ID of the landing page; if not specified, the function returns information about all the landing pages created by a certain user (in the specified network). optional
date string The start date of the range when leads returned are to be generated. The format is YYYY-MM-DD. optional
end_date string The end date of the range when leads returned are to be generated. The format is YYYY-MM-DD. optional

Example:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify a certain network, landing page to get the data for. Also you can specify range of dates when lead gen fields of the requested landing page are to be filled in. Otherwise, you will get information regarding all the lead generations of all the publisher's landing pages.

http://www.moceanmobile.com/mocean_rest_server.php?method=getLandingPageLeadData&privatekey=key_value&network_id=543&landing_page_id=54&date=2010-05-25&end_date=2010-05-26

Successful Response:

<xml>
<landing_page_data>
<lp_id>LANDING_PAGE_ID_HERE</lp_id>
<lp_name>LANDING_PAGE_NAME_HERE</lp_name>
<ip>LANDING_PAGE_IP_HERE</ip>
<ua>LANDING_PAGE_UA_HERE</ua>
<field1>TEXT_INFO_HERE</field1>
...
<fieldN>TEXT_INFO_HERE</fieldN>
<created>LEAD_GENERATION_DATE_AND_TIME_HERE</created>
</landing_page_data>
</xml>

The successful response contains the following elements:

  • Landing_page_data:
lp_id - (integer) the ID of the landing page to get the data for.
lp_name - (string) a name of the landing page to get the data for.
ip - (integer) a ID number of the landing page to get the data for.
ua - (string) user agent of the user been redirected.
fieldN - (string) a text entered into the Nth lead gen textbox.
created - (string) date and time of the lead generation.
The response will contain as many <field> elements as there are lead gen textboxes in a certain landing page.

The number of the <landing_page_data> elements corresponds to the number of leads been generated on a certain Mocean Mobile landing page owned by the specified user.

API Methods To Retrieve Publisher Statistics

A wide range of publisher statistics can be obtained by using API functions described below.

getSiteInfoByDate()

This function returns statistical information regarding a certain site (or all the user sites) for the specified date. If a user is a network owner, the function returns the statistics for all sites of the network for the specified date. The data returned includes the following parameters: the total number of clicks, impressions and requests, total revenue amount and eCPM value.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
date string The date to get the data for. The format is YYYY-MM-DD.required
site_id integerThe ID of the site to get the data for; if not specified, the statistics for all the sites of a certain user will be returned. If the user is the network owner, the function returns the statistics for all sites of this network. To get the publisher site ID, the getPubsiteId() method can be used. optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify 'date' you want to get statistics for.

Optionally, you can specify a certain site to get a report for. Otherwise, you will get statistics for all the sites of the specified user.

http://www.moceanmobile.com/mocean_rest_server.php?method=getSiteInfoByDate&privatekey=key_value&date=2010-04-01&site_id=1

Successful Response:

<xml>
<site>
<name>SITE_NAME_HERE</name>
<site_id>SITE_ID_HERE</site_id>
<total_impressions>TOTAL_IMPRESSIONS_HERE</total_impressions>
<requests>REQUESTS_NUMBER_HERE</requests>
<clicks>CLICKS_NUMBER_HERE</clicks>
<ctr>CTR_NUMBER_HERE</ctr>
<total_revenue>TOTAL_REVENUE_AMOUNT_HERE</total_revenue>
<eCPM>ECPM_VALUE_HERE</eCPM>
</site>
</xml>

The successful response contains the following elements:

  • Site:
name - (string) a name of the site to get the data for.
site_id - (integer) the ID of the site to get the data for.
total_impressions - (integer) the total number of ad impressions regarding a certain site delivered for the specified date.
requests - (integer) the total number of requests regarding a certain site made for the specified date.
clicks - (integer) the total number of clicks regarding a certain site delivered for the specified date.
ctr - (integer) the total number of CTR regarding a certain site delivered for the specified date.
total_revenue - (float) the total number of revenue regarding a certain site received from the ad delivery for the specified date.
eCPM - (float) the eCPM value regarding a certain site for the specified date.

The response will contain as many <site> elements as there are sites owned by the specified user. If 'site_id' specified, the response will contain one <site> element.

Failure Response:

<xml>
<site>
<name>SITE_NAME_HERE</name>
<site_id>SITE_ID_HERE</site_id>
<data>NO DATA for 2010-04-01</data>
</site>
</xml>

getSiteInfoByRange()

This function returns statistical information regarding a certain site (or all the publisher sites) for the specified range of dates. If a user is a network owner, the function returns the statistics for all sites of the network for the specified range of dates.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
enddate string The end date of the reporting range being accessed. The format is YYYY-MM-DD.required
site_id integerThe ID of the site to get the data for; if not specified, the statistics for all the sites of a certain user will be returned. If the user is the network owner, the function returns the statistics for all sites of this network. To get the publisher site ID, the getPubsiteId() method can be used. optional
network_idintegerThe ID of the network to get the data for. optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain range of dates you want to get statistics for.

Optionally, you can specify a certain site to get a report for. Otherwise, you will get statistics for all the sites of the specified user.

http://www.moceanmobile.com/mocean_rest_server.php?method=getSiteInfoByRange&privatekey=key_value&date=2010-04-01&enddate=2010-05-25&site_id=4535

Successful Response:

<xml>
<site>
<name>SITE_NAME_HERE</name>
<site_id>SITE_ID_HERE</site_id>
<total_impressions>TOTAL_IMPRESSIONS_HERE</total_impressions>
<requests>REQUESTS_NUMBER_HERE</requests>
<clicks>CLICKS_NUMBER_HERE</clicks>
<ctr>CTR_VALUE_HERE</ctr>
<total_revenue>TOTAL_REVENUE_AMOUNT_HERE</total_revenue>
<eCPM>ECPM_VALUE_HERE</eCPM>
</site>
</xml>

The successful response contains the following elements:

  • Site:
name - (string) a name of the site to get the data for.
site_id - (integer) the ID of the site to get the data for.
total_impressions - (integer) the total number of impressions regarding a certain site delivered for the specified date range.
requests - (integer) the total number of requests regarding a certain site made for the specified date range.
clicks - (integer) the total number of clicks regarding a certain site delivered for the specified date range.
ctr - (float) the CTR value regarding a certain site for the specified date range.
total_revenue - (float) the total amount of revenue regarding a certain site received from the ad delivery for the specified date range.
eCPM - (float) the eCPM value regarding a certain site for the specified date range.

The response will contain as many <site> elements as there are sites owned by the specified user. If 'site_id' specified, the response will contain one <site> element.

Failure Response:

<xml>
<site>
<name>SITE_NAME_HERE</name>
<site_id>SITE_ID_HERE</site_id>
<data>NO DATA from 2010-04-01 to 2010-05-25</data>
</site>
</xml>

getNetworkSiteInfoByRange()

This function returns statistical information regarding a site (or all the sites) of the specified network for the specified range of dates.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get the data for. To query for specific network IDs, the getNetworkId() API method can be used.required
date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
enddate string The end date of the reporting range being accessed. The format is YYYY-MM-DD.required
site_id integerThe ID of the site to get the data for; if not specified, the statistics for all the network's sites will be returned. To get the site ID, the getPubsiteId() method can be used. optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain range of dates you want to get statistics for.

Optionally, you can specify a certain site to get a report for. Otherwise, you will get statistics for all the sites registered in the specified network.

http://www.moceanmobile.com/mocean_rest_server.php?method=getNetworkSiteInfoByRange&privatekey=key_value&network_id=1&date=2010-04-01&enddate=2010-05-25&site_id=4535

Successful Response:

<xml>
<site>
<name>SITE_NAME_HERE</name>
<site_id>SITE_ID_HERE</site_id>
<publisher_id>PUBLISHER_ID_HERE</publisher_id>
<publisher_name>PUBLISHER_NAME_HERE</publisher_name>
<total_impressions>TOTAL_IMPRESSIONS_HERE</total_impressions>
<requests>REQUESTS_NUMBER_HERE</requests>
<clicks>CLICKS_NUMBER_HERE</clicks>
<revenue>REVENUE_AMOUNT_HERE</revenue>
<ctr>CTR_VALUE_HERE</ctr>
<fillrate>CTR_VALUE_HERE</fillrate>
<eCPM>ECPM_VALUE_HERE</eCPM>
<external_impressions>EXTERNAL_IMPRESSIONS_HERE</external_impressions>
<external_requests>EXTERNAL_REQUESTS_HERE</external_requests>
<external_clicks>EXTERNAL_CLICKS_HERE</external_clicks>
<external_revenue>EXTERNAL_REVENUE_HERE</external_revenue>
<external_ctr>EXTERNAL_CTR_HERE</external_ctr>
<external_fillrate>EXTERNAL_FILLRATE_HERE</external_fillrate>
<external_eCPM>EXTERNAL_ECPM_HERE</external_eCPM>
</site>
</xml>

The successful response contains the following elements:

  • Site:
name - (string) a name of the site to get the data for.
site_id - (integer) the ID of the site to get the data for.
publisher_id - (integer) the ID of the publisher the site belongs to.
publisher_name - (string) the name of the site.
total_impressions - (integer) the total number of impressions regarding a certain site delivered for the specified date range.
requests - (integer) the total number of requests regarding a certain site made for the specified date range.
clicks - (integer) the total number of clicks regarding a certain site delivered for the specified date range.
revenue - (float) the amount of revenue regarding a certain site received from the ad delivery for the specified date range.
ctr - (float) the CTR value regarding a certain site for the specified date range.
eCPM - (float) the eCPM value regarding a certain site for the specified date range.
external_impressions - (integer) the number of external impressions regarding a certain site delivered for the specified date range.
external_requests - (integer) the number of external requests regarding a certain site made for the specified date range.
external_clicks - (integer) the number of external clicks regarding a certain site delivered for the specified date range.
external_revenue - (float) the amount of external revenue regarding a certain site received from the ad delivery for the specified date range.
external_ctr - (float) the external CTR value regarding a certain site for the specified date range.
external_fillrate - (float) the external fill rate value of the specific site in percentage terms.
external_eCPM - (float) the external eCPM value regarding a certain site for the specified date range.


The response will contain as many <site> elements as there are sites in the specified network. If 'site_id' specified, the response will contain only one <site> element.

Failure Response:

<xml>
<login>
<error>ERROR_MESSAGE_HERE</error>
</login>
</xml>

getZoneInfoByRange()

This function returns statistical information in relation to site zones for the specified range of dates.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
enddate string The end date of the reporting range being accessed. The format is YYYY-MM-DD.required
site_id integerThe ID of the site to get the zone data for; if not specified, the statistics for all the publisher’s sites will be returned. To get the publisher site ID, the getPubsiteId() method can be used. optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain period of time you want to get data for.

Optionally, you can specify a certain site to get the zone data for. Otherwise, you will get information on all the zones of all the publisher's sites.

http://www.moceanmobile.com/mocean_rest_server.php?method=getZoneInfoByRange&privatekey=key_value&date=2010-05-25&enddate=2010-05-27&site_id=88

Successful Response:

<xml>
<zone>
<site_name>SITE_NAME_HERE</site_name>
<site_id>SITE_ID_HERE</site_id>
<zone_id>ZONE_ID_HERE</zone_id>
<zone_name>ZONE_NAME_HERE</zone_name>
<total_impressions>ZONE_TOTAL_IMPRESSIONS_HERE</total_impressions>
<requests>ZONE_REQUESTS_NUMBER_HERE</requests>
<clicks>ZONE_CLICKS_NUMBER_HERE</clicks>
<revenue>ZONE_REVENUE_AMOUNT_HERE</revenue>
<ctr>ZONE_CTR_VALUE_HERE</ctr>
<eCPM>ZONE_ECPM_VALUE_HERE</eCPM>
</zone>
</xml>

The successful response contains the following elements:

  • Zone:
site_name - (string) a name of the site to get the zone data for.
site_id - (integer) the ID of the site to get the zone data for.
zone_id - (integer) the ID of the zone that is belong to a certain site to get the data for.
zone_name - (string) a name of the zone that is belong to a certain site to get the data for.
total_impressions - (integer) the total number of impressions regarding a certain zone delivered for the specified date range.
requests - (integer) the total number of requests regarding a certain zone made for the specified date range.
clicks - (integer) the total number of clicks regarding a certain zone delivered for the specified date range.
revenue - (integer) the total number of revenue regarding a certain zone received from the ad delivery for the specified date range.
ctr - (float) the CTR value regarding a certain zone for the specified date range.
eCPM - (float) the eCPM value regarding a certain zone for the specified date range.

The response will contain as many <zone> elements as there are zones in the specified site (or in all the publisher's sites).

Failure Response:

<xml>
<zone>
<site_name>SITE_NAME_HERE</site_name>
<site_id>SITE_ID_HERE</site_id>
<zone_id>ZONE_ID_HERE</zone_id>
<zone_name>ZONE_NAME_HERE</zone_name>
<data>NO DATA from 2010-05-25 to 2010-05-27</data>
</zone>
</xml>

getNetworkZoneInfoByRange()

This function returns statistical information in relation to the zones for the specified network and range of dates.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get the data for. To query for specific network IDs, the getNetworkId() API method can be used.required
date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
enddate string The end date of the reporting range being accessed. The format is YYYY-MM-DD.required
site_id integerThe ID of the site to get the zone data for; if not specified, the statistics for all the network's sites will be returned. To get the site ID, the getPubsiteId() method can be used. optional
zone_idintegerThe ID of the zone to get the data for.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain period of time you want to get data for.

Optionally, you can specify a certain site to get the zone data for. Otherwise, you will get information on all the zones of all the network's sites.

http://www.moceanmobile.com/mocean_rest_server.php?method=getNetworkZoneInfoByRange&privatekey=key_value&network_id=1&date=2010-05-25&enddate=2010-05-27&site_id=88

Successful Response:

<xml>
<zone>
<site_name>SITE_NAME_HERE</site_name>
<site_id>SITE_ID_HERE</site_id>
<zone_id>ZONE_ID_HERE</zone_id>
<zone_name>ZONE_NAME_HERE</zone_name>
<publisher_id>PUBLISHER_ID_HERE</publisher_id>
<publisher_name>PUBLISHER_NAME_HERE</publisher_name>
<total_impressions>ZONE_TOTAL_IMPRESSIONS_HERE</total_impressions>
<requests>ZONE_REQUESTS_NUMBER_HERE</requests>
<clicks>ZONE_CLICKS_NUMBER_HERE</clicks>
<revenue>ZONE_REVENUE_AMOUNT_HERE</revenue>
<ctr>ZONE_CTR_VALUE_HERE</ctr>
<fillrate>CTR_VALUE_HERE</fillrate>
<eCPM>ZONE_ECPM_VALUE_HERE</eCPM>
<external_impressions>EXTERNAL_IMPRESSIONS_HERE</external_impressions>
<external_requests>EXTERNAL_REQUESTS_HERE</external_requests>
<external_clicks>EXTERNAL_CLICKS_HERE</external_clicks>
<external_revenue>EXTERNAL_REVENUE_HERE</external_revenue>
<external_ctr>EXTERNAL_CTR_HERE</external_ctr>
<external_fillrate>EXTERNAL_FILLRATE_HERE</external_fillrate>
<external_eCPM>EXTERNAL_ECPM_HERE</external_eCPM>
</zone>
</xml>

The successful response contains the following elements:

  • Zone:
site_name - (string) a name of the site to get the zone data for.
site_id - (integer) the ID of the site to get the zone data for.
zone_id - (integer) the ID of the zone that is belong to a certain site to get the data for.
zone_name - (string) a name of the zone that is belong to a certain site to get the data for.
publisher_id - (integer) the ID of the publisher the zone belongs to.
publisher_name - (string) the name of the publisher the zone belongs to.
total_impressions - (integer) the total number of impressions regarding a certain zone delivered for the specified date range.
requests - (integer) the total number of requests regarding a certain zone made for the specified date range.
clicks - (integer) the total number of clicks regarding a certain zone delivered for the specified date range.
revenue - (integer) the total number of revenue regarding a certain zone received from the ad delivery for the specified date range.
ctr - (float) the CTR value regarding a certain zone for the specified date range.
fillrate - (float) the value of zone fillrate.
eCPM - (float) the eCPM value regarding a certain zone for the specified date range.
external_impressions - (integer) the number of external impressions regarding a certain zone delivered for the specified date range.
external_requests - (integer) the number of external requests regarding a certain zone made for the specified date range.
external_clicks - (integer) the number of external clicks regarding a certain zone delivered for the specified date range.
external_revenue - (float) the amount of external revenue regarding a certain zone received from the ad delivery for the specified date range.
external_ctr - (float) the external CTR value regarding a certain zone for the specified date range.
external_fillrate - (float) the external value of zone fillrate.
external_eCPM - (float) the external eCPM value regarding a certain zone for the specified date range.

The response will contain as many <zone> elements as there are zones in the specified network (or in all the publisher's zone).

Failure Response:

<xml>
<login>
<error>ERROR_MESSAGE_HERE</error>
</login>
</xml>

getRawRequestsByZone()

This function returns information in relation to the number of raw requests to each zone of a certain site or network.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get the statistics for. If not specified, the statistics for all the networks of a certain user will be returned.To query for specific network IDs, the getNetworkId() API method can be used. optional
pubsite_id integer The ID of the site to get the zone data for. If not specified and the user is an owner of the network, the function will return the statistics for all sites of this network. To get the site ID, the getPubsiteId() method can be used. optional
start_date string The start date of the reporting range being accessed. If not specified, the end date will be set to 48 hours back from the current moment.The format is YYYY-MM-DD.optional
end_date string The end date of the reporting range being accessed. If not specified, it will be set to 24 hours back from the current moment. The format is YYYY-MM-DD.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify certain network, site and range of dates to get the data for. Otherwise, you will get the information in relation to all the sites for two days prior to the current one.

http://www.moceanmobile.com/mocean_rest_server.php?method=getRawRequestsByZone&privatekey=key_value&network_id=5342&pubsite_id=534&start_date=2008-05-25&end_date=2010-05-26

Successful Response:

<xml>
<zone_requests>
<raw_requests>REQUSETS_NUMBER_HERE</raw_requests>
<pubsite_id>SITE_ID_HERE</pubsite_id>
<zone_id>ZONE_ID_HERE</zone_id>
<pubsite_name>SITE_NAME_HERE</pubsite_name>
<zone_name>ZONE_NAME_HERE</zone_name>
</zone_requests>
</xml>

The successful response contains the following elements:

  • Zone_requests:
raw_requests - (integer) the total number of raw requests to a certain zone of a certain site or network made for the specified date range.
pubsite_id - (integer) the ID of the site to get the zone data for.
zone_id - (integer) the ID of the zone that is belong to the specified site to get the data for.
pubsite_name - (string) a name of the site to get the zone data for.
zone_name - (string) a name of the zone that is belong to the specified site to get the data for.

The response will contain as many <zone_requests> elements as there are zones in the specified site/network or in all the user's sites.

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

API Methods To Retrieve Creative Statistics

getAdDataByRange()

This function returns statistical information (number of impressions, clicks and conversions, amount of cost) in relation to all the user ads for a certain period of time (if specified) or for the start_date.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get data for. If not specified, the statistics for all the networks of a certain user will be returned. To query for specific network IDs, the getNetworkId() API method can be used. optional
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
end_date string The end date of range. The format is YYYY-MM-DD. If not specified, it will be set to the start_date value.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify 'start_date' since which you want to get statistics.

Optionally, you can specify a certain network and the end of time period to generate a report for. Otherwise, you will get the report generated for all the user's networks for the start date only.

http://www.moceanmobile.com/mocean_rest_server.php?method=getAdDataByRange&privatekey=key_value&start_date=2010-05-25&end_date=2010-06-01

Successful Response:

<xml>
<ad_report>
<ad_name>AD_NAME</ad_name>
<network_name>NETWORK_NAME</network_name>
<advertiser_id>ADVERTISER_ID</advertiser_id>
<advertiser_name>ADVERTISER_NAME</advertiser_name>
<activation_date>LINE_ITEM_ACTIVATION_DATE</activation_date>
<expiration_date>LINE_ITEM_EXPIRATION_DATE</expiration_date>
<ad_type>AD_TYPE</ad_type>
<campaign_id>ORDER_ID</campaign_id>
<ad_id>AD_ID</ad_id>
<cost>AD_COSTS</cost>
<impressions>AD_IMPRESSIONS_NUMBER</impressions>
<clicks>AD_CLICKS_NUMBER</clicks>
</ad_report>
</xml>

The successful response contains the following elements:

  • Ad_report:
ad_name - (string) a name of the line item that is created in a certain network.
network_name - (string) a name of the network to get the data for.
advertiser_id - (integer) the ID of the advertiser who has created the ad in the specified network.
advertiser_name - (string) a name of the advertiser who has created the ad in the specified network.
activation_date - (string) date and time of the line item activation.
expiration_date - (string) date and time of the line item expiration.
ad_type - (integer) the type of the ad (1- text; 2 - image; 5 - richmedia; 6 - sms ); if the value is more than 1000, the ad is a third party.
campaign_id - (integer) the ID of the user's order where the ad is running on.
ad_id - (integer) the ID of the line item that is created in the requested network.
cost - (numeric) the cost value spent by advertiser in ad clicks and shows (line item price).
impressions - (integer) the total number of ad impressions regarding a certain network shown for the specified date range (is shown for a line item).
clicks - (integer) the total number of clicks regarding a certain network made for the specified date range (shown for a line item).

The response will contain as many <ad_report> elements as there are ads in the network (or in all the user's networks).

Failure Response:

<xml>
<error>no stats</error>
</xml>

getAdInfoByDate()

This function returns statistical information (country, number of impressions and clicks, amount of cost) in relation to all the user ads for the specified date.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
date stringThe date that the statistics is to be returned for. The format is YYYY-MM-DD. required

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a 'date' you want to get statistics for.

http://www.moceanmobile.com/mocean_rest_server.php?method=getAdInfoByDate&privatekey=key_value&date=2010-05-24

Successful Response:

<xml>
<ad>
<name>AD_NAME</name>
<id>AD_ID</id>
<country>
<name>COUNTRY_NAME</name>
<impressions>AD_IMPRESSIONS_NUMBER</impressions>
<clicks>AD_CLICKS_NUMBER</clicks>
<cost>AD_COSTS</cost>
</country>
</ad>
</xml>

The successful response contains the following elements:

  • Ad:
name - (string) a name of the line item.
id - (integer) the ID of the line item.
country - (Country) a list of countries where the ad was shown.
  • Country:
name - (string) a name of the country where the ad was shown.
impressions - (integer) the total number of ad impressions shown in the certain country per the specified date (returned for the line item).
clicks - (integer) the total number of clicks made in the certain country per the specified date (returned for the line item).
cost - (numeric) the cost value spent by advertiser in the ad delivery in the certain country per the specified date (returned for the line item).
The number of <country> elements corresponds to the number of countries where the ad was shown.

The response will contain as many <ad> elements as there are ads in all user's networks.

No-Ads Response:

<xml>
<ad>
<name>No Ads</name>
<id>0</id>
</ad>
<xml>

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getAdInfoByRange()

This function returns statistical information (country, number of impressions and clicks, amount of cost) in relation to all the user ads for the specified date.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
date stringThe start date of the reporting range being accessed. The format is YYYY-MM-DD. required
enddate stringThe end date of the reporting range being accessed. The format is YYYY-MM-DD. required

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify a certain range of dates you want to get statistics for.

http://www.moceanmobile.com/mocean_rest_server.php?method=getAdInfoByRange&privatekey=const&date=2010-05-25&enddate=2010-05-27

Successful Response:

<xml>
<ad>
<name>AD_NAME</name>
<id>AD_ID</id>
<country>
<name>COUNTRY_NAME</name>
<impressions>AD_IMPRESSIONS_NUMBER</impressions>
<clicks>AD_CLICKS_NUMBER</clicks>
<cost>AD_COSTS</cost>
</country>
</ad>
</xml>

The successful response contains the following elements:

  • Ad:
name - (string) a name of the line item.
id - (integer) the ID of the line item.
country - (Country) a list of countries where the ad was shown.
  • Country:
name - (string) a name of the country where the ad was shown.
impressions - (integer) the total number of ad impressions shown in the certain country for the specified date range (returned for the line item).
clicks - (integer) the total number of clicks made in the certain country for the specified date range (returned for the line item).
cost - (numeric) the cost value spent by advertiser in the ad delivery in the certain country for the specified date range (returned for the line item).
The number of <country> elements corresponds to the number of countries where the ad was shown for the specified date range.

The response will contain as many <ad> elements as there are ads (line items) in all user's networks.

No-Ads Response:

<xml>
<ad>
<name>No Ads</name>
<id>0</id>
</ad>
<xml>

Failure Response:

<xml>
<login>
<error>API Key is Invalid.</error>
</login>
</xml>

getCampaignGoals()

This function returns the goal and the actual annual statistics (for the previous 12 months) as relates to impressions of the requested order up to the specified month breaking down the data by line items of the order; it includes the following data:

  • total number of impressions set for the specific line item;
  • the goal number of ad impressions to be delivered from the activation date till the end of the month specified;
  • the actual number of impressions that have been delivered since the line item started;
  • optimal number of impressions to be delivered daily.

This method returns the data ONLY for line items with the total impressions number set!

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get data for. If not specified, the statistics for all the networks of a certain user will be returned. To query for specific network IDs, the getNetworkId() API method can be used. optional
campaigngroup_id integerThe ID of the order to get the line items' statistics for; if not specified, function returns the data for all the line items of all orders within the specified network.optional
month integerA month (default is the current month) up to, but not including, that the annual statistics is to be returned, i.e. statistics will be returned for the previous 12 months of the date specified. optional
year integerA year (default is the current year) up to and including that the statistics is to be returned, i.e. function returns statistics for 12 months up to, but not including, the specified (or current) month of the specified (or current) year. optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify certain 'network_id', 'campaigngroup_id', 'month' and 'year' to generate a report for. Otherwise, you will get the annual report generated for all the user's line items and networks up to the current month of the current year.

http://www.moceanmobile.com/mocean_rest_server.php?method=getCampaignGoals&privatekey=key_value&campaigngroup_id=5432&month=9&year=2010

Successful Response:

<xml>
<campaign_group>
<network_id>NETWORK_ID_HERE</network_id>
<id>LINE_ITEM_ID_HERE</id>
<name>LINE_ITEM_NAME_HERE</name>
<impression_month_goal>GOAL_IMPRESSIONS_NUMBER</impression_month_goal>
<optimal_daily_delivered>OPTIMAL_DAILY_DELIVERED_NUMBER</optimal_daily_delivered>
<optimal_total_delivered>OPTIMAL_TOTAL_DELIVERED_NUMBER</optimal_total_delivered>
<delivered_today>NUMBER_OF_TODAY_DELIVERED_IMPRESSIONS</delivered_today>
<delivered_total>NUMBER_OF_TOTAL_DELIVERED_IMPRESSIONS</delivered_total>
<month_impressions>ACTUAL_IMPRESSIONS_NUMBER</month_impressions>
<impression_month1_goal>IMPRESSIONS</impression_month1_goal>
<impression_month2_goal>IMPRESSIONS</impression_month2_goal>
...
<impression_month12_goal>IMPRESSIONS</impression_month12_goal>
<activation_date>LINE_ITEM_ACTIVATION_DATE</activation_date>
<expiration_date>LINE_ITEM_EXPIRATION_DATE</expiration_date>
<overall_goal>LINE_ITEM_TOTAL_ADVIEWS_LIMIT</overall_goal>
</campaign_group>
</xml>

The successful response contains the following elements:

  • Campaign_group:
network_id - (integer) the ID of the network within which the order is created.
id - (integer) the ID of the line item the data is obtained for.
name - (string) a name of the line item the data is obtained for.
impression_month_goal - (integer) the total number of ad impressions that was planned to be delivered for an year up to the specified month of the specified year.
optimal_daily_delivered - (integer) the optimal number of ad impressions delivered per a day.
optimal_total_delivered - (integer) the optimal number of total delivered ads impressions.
delivered_today - (integer) the number of ads impressions delivered on the current day.
delivered_total - (integer) the total number of ad impressions delivered.
impression_monthN_goal - (integer) the total number of ad impressions delivered (or expected to be delivered if month specified > the current month) per N-th month. Months are counted from the specified (or current) month of the previous year up to the previous month of the specified (or current) year. (For example, if you have specified month=6, year=2011, impressions number delivered from 6/2010 till 5/2011 inclusive will be returned, i.e. 'month1' will correspond to 6/2010, 'month12' will correspond to 5/2011)
activation_date - (string) date and time of the line item activation.
expiration_date - (string) date and time of the line item expiration.
overall_goal - (integer) the total number of ad impressions that was set for the line item.

The response will contain as many <campaign_group> elements as there are line items with limited impressions number within the requested order/network (or in all user's networks).

Failure Response:

<xml>
<error>no stats</error>
</xml>

getCampaignDataByAdvertiser()

This function returns statistical information (number of impressions and clicks, amount of cost) in relation to a certain ad or all user ads created for a certain user (advertiser) for a certain period of time.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
advertiser_idintegerThe id of the advertiser to get the ad data for.required
network_idintegerThe id of the network to get the ad data for.optional
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify 'advertiser_id' which you want to get statistics for.

http://www.moceanmobile.com/mocean_rest_server.php?method=getCampaignDataByAdvertiser&privatekey=key_value&advertiser_id=2222222

Successful Response:

<xml>
<campaign_stats>
<advertiser_id>ADVERTISER_ID_HERE</advertiser_id>
<advertiser_name>ADVERTISER_NAME_HERE</advertiser_name>
<campaign_id>ORDER_ID_HERE</campaign_id>
<creative_id>LINEITEM_ID_HERE</creative_id>
<creative_name>LINEITEM_NAME_HERE</creative_name>
<company_name>ADVERTISER_COMPANY_NAME_HERE</company_name>
<campaign_name>ORDER_NAME_HERE</campaign_name>
<network_id>NETWORK_ID_HERE</network_id>
<cost>COST_HERE</cost>
<impressions>IMPRESSIONS_HERE</impressions>
<clicks>CLICKS_HERE</clicks>
</campaign_stats>
</xml>

The successful response contains the following elements:

  • Campaign_stats:
advertiser_id - (integer) the ID of the advertiser who has created the ad.
advertiser_name - (string) a name of the advertiser who has created the ad.
campaign_id - (integer) the ID of the order within which the ad is delivered.
creative_id - (integer) the ID of the line item.
creative_name - (string) a name of the line item.
company_name - (string) a name of the advertiser's company.
campaign_name - (string) a name of the order within which the ad is delivered.
network_id - (integer) the ID of the network within which the order is created.
cost - (numeric) the cost value spent by advertiser in the ad delivery for the specified date range (or the current date).
impressions - (integer) the total number of ad impressions delivered for the specified date range (or the current date).
clicks - (integer) the total number of ad clicks delivered for the specified date range (or the current date).

Failure Response:

<xml>
<adfeed>
<error>no stats</error>
</adfeed>
</xml>

getCampaignDataByRange()

This function returns statistical information (number of impressions and clicks, amount of cost) in relation to a certain ad or all user ads created in a certain network (if ad and network are specified) for a certain period of time.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.required
campaign_idintegerThe ID of the line item to get the optional statistics for; if not specified, function returns the data for all the line items of a certain user (in a certain network).optional
network_id integerThe ID of the network to the get data for. If not specified, the statistics for all the networks of a certain user will be returned. To query for specific network IDs, the getNetworkId() API method can be used. optional
end_date string The end date of the reporting range being accessed. If not specified, statistics will be returned for the start_date only. The format is YYYY-MM-DD.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value and specify 'start_date' which you want to get statistics for.

Optionally, you can specify 'network_id', 'campaign_id' and the end of a data range ('end_date') to generate a report for. Otherwise, you will get the report generated for all user's ads and networks for the start_date only.

http://www.moceanmobile.com/mocean_rest_server.php?method=getCampaignDataByRange&privatekey=key_value&start_date=2010-05-25

Successful Response:

<xml>
<campaign_stats>
<creative_id>LINE_ITEM_ID_HERE</creative_id>
<creative_name>LINE_ITEM_NAME_HERE</creative_name>
<campaign_id>ORDER_ID_HERE</campaign_id>
<advertiser_id>ADVERTISER_ID_HERE</advertiser_id>
<advertiser_name>ADVERTISER_NAME_HERE</advertiser_name>
<company_name>ADVERTISER'S_COMPANY_NAME</company_name>
<campaign_name>ORDER_NAME_HERE</campaign_name>
<network_id>NETWORK_ID_HERE</network_id>
<cost>COST_VALUE_HERE</cost>
<impressions>AD_IMPRESSIONS_NUMBER</impressions>
<clicks>AD_CLICKS_NUMBER</clicks>
</campaign_stats>
</xml>

The successful response contains the following elements:

  • Campaign_stats:
creative_id - (integer) the ID of the line item created within the certain order of the certain network.
creative_name - (string) a name of the line item created within the certain order of the certain network.
campaign_id - (integer) the ID of the order within which the ad is delivered.
advertiser_id - (integer) the ID of the advertiser who has created the ad.
advertiser_name - (string) a name of the advertiser who has created the ad.
company_name - (string) a name of the advertiser's company.
campaign_name - (string) a name of the order within which the ad is delivered.
network_id - (integer) the ID of the network within which the order is created.
cost - (numeric) the cost value spent by advertiser in the ad delivery for the specified date range (returned for the line item).
impressions - (integer) the total number of ad impressions delivered for the specified date range (returned for the line item).
clicks - (integer) the total number of ad clicks delivered for the specified date range (returned for the line item).

The response will contain as many <campaign_stats> elements as there are ads in the user's order(s) or network (or in all user's networks).

Failure Response:

<xml>
<error>no stats</error>
</xml>

getCampaignZoneByRange()

This function returns ads statistics (the number of impressions and clicks delivered and the amount of costs) broken down by zones for the specified date range.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
pubsite_id integerThe ID of the site to get the zone data for; if not specified, the statistics for all the sites of a certain user (in the specified network) will be returned.optional
network_id integerThe ID of the network to get data for. If the ID of the super-network is specified the data will be returned for the super-network and its sub-networks. If not specified, the statistics for all the networks of a certain user will be returned. To query for specific network IDs, the getNetworkId() API method can be used. optional
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.optional
end_date string The date up to (but not including) which the data should be returned. If not specified, statistics will be returned for the start_date only. The format is YYYY-MM-DD.
NOTE: The specified date range should not exceed a 1 month period.
optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace key_value with your real private key value.

Optionally, you can specify pubsite_id, network_id and the certain range of dates to generate a report for. Otherwise, you will get the report generated for all the user's networks for the current date.

http://www.moceanmobile.com/mocean_rest_server.php?method=getCampaignZoneByRange&privatekey=key_value&start_date=2010-05-25&end_date=2010-05-26

Successful Response:

<xml>
<campaign_stats>
<creative_id>LINEITEM_ID_HERE</creative_id>
<creative_name>LINEITEM_NAME_HERE</creative_name>
<campaign_id>ORDER_ID</campaign_id>
<advertiser_id>ADVERTISER_ID</advertiser_id>
<advertiser_name>ADVERTISER_NAME</advertiser_name>
<company_name>ADVERTISER'S_COMPANY_NAME</company_name>
<campaign_name>ORDER_NAME</campaign_name>
<zone_id>ZONE_ID</zone_id>
<zone_name>ZONE_NAME</zone_name>
<pubsite_id>SITE_ID</pubsite_id>
<network_id>NETWORK_ID</network_id>
<cost>COST_AMOUNT</cost>
<impressions>AD_IMPRESSIONS_NUMBER</impressions>
<clicks>AD_CLICKS_NUMBER</clicks>
</campaign_stats>
</xml>

The successful response contains the following elements:

  • Campaign_stats:
creative_id - (integer) the ID of the line item.
creative_name - (string) a name of the line item.
campaign_id - (integer) the ID of the order within which the ad is delivered.
advertiser_id - (integer) the ID of the advertiser who has created the ad.
advertiser_name - (string) a name of the advertiser who has created the ad.
company_name - (string) a name of the advertiser's company.
campaign_name - (string) a name of the order within which the ad is delivered.
zone_id - (integer) the ID of the zone to get the data for.
zone_name - (string) a name of the zone to get the data for.
pubsite_id - (integer) the ID of the publisher site relating to the zone.
network_id - (integer) the ID of the network within which the order is created.
cost - (numeric) the cost value spent by advertiser in the ad delivery for the specified date range (or the current date).
impressions - (integer) the total number of ad impressions delivered for the specified date range (or the current date).
clicks - (integer) the total number of ad clicks delivered for the specified date range (or the current date).

The response will contain as many <campaign_stats> elements as there are ads and different zones in the network (or in all user's networks).

Failure Response:

<xml>
<error>no stats</error>
</xml>

getAdFeedData()

This function returns third party statistics according to the report type selected for the certain period of dates.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
report_typestring A type of report: hourly, daily or monthly.optional
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD.optional
end_date string The end date of the reporting range being accessed. If not specified, statistics will be returned for the period from the start_date up to the current date. The format is YYYY-MM-DD.optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace 'key_value' with your real private key value.

Optionally, you can specify certain 'report_type' and range of dates to generate a report for. Otherwise, you will get the daily report generated for the current date.

http://www.moceanmobile.com/mocean_rest_server.php?method=getAdFeedData&privatekey=key_value&report_type=daily&start_date=2010-05-25

Successful Hourly Response:

<xml>
<adfeed>
<name>ADFEED_NAME</name>
<imps>TOTAL_AD_IMPRESSIONS_NUMBER</imps>
<impsThirdParty>THIRD_PARTY_IMPRESSIONS_NUMBER</impsThirdParty>
<impsMojivaFeed>LOCAL_AD_IMPRESSIONS_NUMBER</impsMojivaFeed>
<clicks>TOTAL_CLICKS_NUMBER</clicks>
<clicksThirdParty>THIRD_PARTY_CLICKS_NUMBER</clicksThirdParty>
<clicksMojivaFeed>LOCAL_CLICKS_NUMBER</clicksMojivaFeed>
<ctr>CTR_VALUE</ctr>
<revenue>REVENUE_VALUE</revenue>
</adfeed>
</xml>

Successful Daily and Monthly Responses:

<xml>
<adfeed>
<name>ADFEED_NAME</name>
<year>YEAR_HERE</year>
<month>MONTH_HERE</month>
<day>DAY_HERE</day>
<imps>TOTAL_AD_IMPRESSIONS_NUMBER</imps>
<impsThirdParty>THIRD_PARTY_IMPRESSIONS_NUMBER</impsThirdParty>
<impsMojivaFeed>LOCAL_AD_IMPRESSIONS_NUMBER</impsMojivaFeed>
<clicks>TOTAL_CLICKS_NUMBER</clicks>
<clicksThirdParty>THIRD_PARTY_CLICKS_NUMBER</clicksThirdParty>
<clicksMojivaFeed>LOCAL_CLICKS_NUMBER</clicksMojivaFeed>
<ctr>CTR_VALUE</ctr>
<revenue>REVENUE_VALUE</revenue>
<ext_clicks>EXTERNAL_CLICKS_NUMBER</ext_clicks>
<ext_impressions>EXTERNAL_IMPRESSIONS_NUMBER</ext_impressions>
<ext_fillrate>EXTERNAL_FILLRATE<ext_fillrate>
</adfeed>
</xml>

The successful response contains the following elements (te data is returned for the order basis):

  • Adfeed:
name - (string) the name of the Ad feed.
year - (integer) the year the statistics data for the order returned for.
month - (integer) the month the statistics data for the order returned for.
day - (integer) the day the statistics data for the order returned for.
imps - (integer) the total number of ad feed impressions delivered for the specified date range.
impsThirdParty - (integer) the total number of ad feed impressions delivered for the specified date range.
impsMojivaFeed - (integer) the local number of ad feed impressions delivered for the specified date range.
clicks - (integer) the total number of ad feed clicks delivered for the specified date range.
clicksThirdParty - (integer) the total number of ad feed clicks delivered for the specified date range.
clicksMojivaFeed - (integer) the local number of ad feed clicks delivered for the specified date range.
ctr - (float) the CTR value regarding a certain ad feed for the specified date range.
revenue - (integer) the local value of revenue received from the ad feed delivery for the specified date range.
ext_clicks - (integer) the number of ad feed clicks imported from the third party site for the specified date range.
ext_impressions - (integer) the number of ad feed impressions imported from the third party site for the specified date range.
ext_fillrate - (integer) the ad feed fill rate in percentage terms.

The number of <adfeed> elements corresponds to the ad feeds number of the specified user.

Failure Response:

<xml>
<adfeed>
<error>no stats</error>
</adfeed>
</xml>

Inventory Forecasting API Methods

API methods described below provide you with an access to a forecasting information concerned mobile inventory - the sum total of all the impressions available - for a certain order as well as an ad and a zone.

The inventory information returned includes the data for all ads (line items) without specifying by booked and held line item types.

getZoneInventory()

Returns the network, site and zone ids with the number of requests expected on the certain zone for the specified date range. A list of line items assigned to the zone with expected requests is also returned.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
network_id integerThe ID of the network to get the forecasting inventory information broken down by zones for. optional*
pubsite_id integerThe ID of the publisher site to get the forecasting inventory information broken down by zones for. optional*
zone_id integerThe ID of the zone to get the forecasting inventory information for.optional*
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (2 weeks for this function).optional

* At least one of parameters (network_id, pubsite_id or zone_id) should be specified.

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real zone ID (network ID or pubsite ID) you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for 2 weeks from the current moment.

http://moceanmobile.com/mocean_api.php?method=getZoneInventory&privatekey=key_value&network_id=252&pubsite_id=5576&zone_id=14269&start_date=2012-02-01&end_date=2012-02-29

Successful Response:

<xml>
<inventory>
<network_id>NETWORK_ID</network_id>
<pubsite_id>SITE_ID</pubsite_id>
<zone_id>ZONE_ID</zone_id>
<goal>
<campaigns>
<campaign>
<id>LINE_ITEM_ID</id>
<name>LINE_ITEM_NAME</name>
<priority_type>PRIORITY_TYPE_NUMBER</priority_type>
<priority>1</priority>
</campaign>
</campaigns>
<sum>LINE_ITEM_REQUEST_NUMBER</sum>
</goal>
<requests>TOTAL_REQUESTS_NUMBER</requests>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
network_id - (integer) the ID of the network to get the zone forecasting inventory information for.
pubsite_id - (integer) the ID of the site within the network to get the zone forecasting inventory information for.
zone_id - (integer) the ID of the zone to get the forecasting inventory information for.
goals - (Goals) line items assigned to the zone with requests expected.
requests - (integer) the total number of requests expected for the specified date range.
  • Goals:
campaigns - (Campaigns) the list of line items to be shown.
sum - the total number of requests expected regarding to line items been already assigned to the zone.
  • Campaigns:
  • campaign:
id - (integer) the ID of the line item expected to be shown on the specified zone.
name - (string) the name of the line item.
priority_type - (integer) a priority type of the line item.
priority - (integer) the priority rating set for the priority type.
The number of <campaign> elements corresponds to the number of line items to be shown on the specified zone.

The response will contain as many <inventory> elements as there are zones in the network (if network_id specified) or in the site (if pubsite_id specified). If zone_id has been specified in the request, the amount of the <inventory> elements will be one.

Failure Response:

A failure response could be like this:

<getZoneInventory generator="zend" version="1.0">
<msg>Invalid Private Key</msg>
<status>0</status>
</getZoneInventory>

OR:

<getZoneInventory generator="zend" version="1.0">
<msg>
None of pubsite_id, zone_id, network_id is specified
</msg>
<status>0</status>
</getZoneInventory>

OR like this:

<getZoneInventory generator="zend" version="1.0">
<msg>Date format is not valid</msg>
<status>0</status>
</getZoneInventory>

getInventoryZone()

Returns the zone name, the number of impressions (both for booked and held line items together) expected to be shown on the specified zone for each day in the specified date range.

Parameters:

Parameter Type Description Required?
privatekey string The unique alphanumeric identifier generated for Mocean registered users to be able to use REST API functionality. required
zone_id integerThe ID of the zone to get the forecasting inventory information for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional


Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real zone ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryZone&privatekey=key_value&zone_id=14269&start_date=2011-08-01&end_date=2011-08-03

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<zone>ZONE_NAME</zone>
<impressions>IMPRESSIONS_NUMBER</impressions>
<clicks>CLICKS_NUMBER</clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
zone - (string) a name of the zone to get the data for.
impressions - (integer) the total number of zone impressions (both for booked and held line items) expected on day specified in the <date> element.
clicks - (integer) the total number of zone clicks (both for booked and held line items) expected on day specified in the <date> element.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryCampaign()

Returns the number of impressions expected for the specified order's line items (no matter if these are booked line items or held).

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
campaign_id integerThe ID of the order to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment). optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real order ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryCampaign&privatekey=key_value_here&campaign_id=9759&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<impressions>IMPRESSIONS_NUMBER</impressions>
<clicks>CLICKS_NUMBER</clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
impressions - (integer) the total number of order impressions (sum of impressions for all line items of this order) expected on day specified in the <date> element.
clicks - (integer) the total number of order clicks (sum of clicks for all line items of this order) expected on day specified in the <date> element.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryAd()

Returns the number of impressions of the specified ad expected on each day of the specified date range.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
ad_id integerThe ID of the line item to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_datestring The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real ad ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryAd&privatekey=key_value_here&ad_id=11419&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<impressions>IMPRESSIONS_NUMBER</impressions>
<clicks>CLICKS_NUMBER</clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
impressions - (integer) the total number of ad impressions expected for the line item on the day specified in the <date> element.
clicks - (integer) the total number of ad clicks expected for the line item the on day specified in the <date> element.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryZoneCampaigns()

Returns the number of impressions for each order the ad of which is expected to be shown on a certain zone.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
zone_id integerThe ID of the zone to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real zone ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryZoneCampaigns&privatekey=key_value_here&zone_id=14269&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<campaigns>
<campaign>
<id>ORDER_ID</id>
<name>ORDER_NAME</name>
<impressions>ORDER_IMPRESSIONS_NUMBER</impressions>
<clicks>ORDER_CLICKS_NUMBER</clicks>
</campaign>
</campaigns>
<total_impressions>TOTAL_IMPRESSIONS_NUMBER</total_impressions>
<total_clicks>TOTAL_CLICKS_NUMBER</total_clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
campaigns: - (Campaigns) the list of orders to be shown.
total_impressions - (integer) the total number of impressions expected to be shown on day specified in the <date> element.
total_clicks - (integer) the total number of clicks expected to be shown on day specified in the <date> element.
  • Campaigns:
  • campaign:
id - (integer) the ID of the order the ad of which is expected to be shown on the specified zone
name - (string) the name of the order.
impressions - (integer) the total number of order's line items impressions expected on day specified in the <date> element.
clicks - (integer) the total number of order's line items clicks expected on day specified in the <date> element.
The number of <campaign> elements corresponds to the number of orders the ads of which are to be shown on the specified zone.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryZoneAds()

Returns the number of impressions for each ad expected to be shown on a certain zone.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
zone_id integerThe ID of the zone to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real zone ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryZoneAds&privatekey=key_value_here&zone_id=14269&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<ads>
<ad>
<id>LINE_ITEM_ID</id>
<name>LINE_ITEM_NAME</name>
<impressions>LINE_ITEM_IMPRESSIONS_NUMBER</impressions>
<clicks>LINE_ITEM_CLICKS_NUMBER</clicks>
</ad>
</ads>
<total_impressions>TOTAL_IMPRESSIONS_NUMBER</total_impressions>
<total_clicks>TOTAL_CLICKS_NUMBER</total_clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
ads: - (Ads) the list of ads (line items) to be shown.
total_impressions - (integer) the total number of impressions expected to be shown on day specified in the <date> element.
total_clicks - (integer) the total number of clicks expected to be shown on day specified in the <date> element.
  • Ads:
  • ad:
id - (integer) the ID of the ad (line item) expected to be shown on the specified zone
name - (string) the name of the ad (line item).
impressions - (integer) the total number of ad impressions expected on day specified in the <date> element.
clicks - (integer) the total number of ad clicks expected on day specified in the <date> element.
The number of <ad> elements corresponds to the number of ads (line items) to be shown on the specified zone.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryCampaignDetails()

Returns inventory forecasting report for a certain line item (booked or held) broken down by zones and days of the specified date range.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
campaign_id integerThe ID of the order to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real order ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryCampaignDetails&privatekey=key_value_here&campaign_id=9759&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<zones>
<zone>
<id>ZONE_ID</id>
<name>ZONE_NAME</name>
<impressions>IMPRESSIONS_NUMBER_FOR_THE_ZONE</impressions>
<clicks>CLICKS_NUMBER_FOR_THE_ZONE</clicks>
</zone>
</zones>
<total_impressions>TOTAL_IMPRESSIONS_NUMBER</total_impressions>
<total_clicks>TOTAL_CLICKS_NUMBER</total_clicks>
</inventory>
</xml>

The successful response contains the following elements:

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
zones: - (Zones) the list of zones that the order's line items are expected to be shown on.
total_impressions - (integer) - the total number of order impressions (the sum of impressions for all line items of this order) expected to be shown on day specified in the <date> element.
total_clicks - (integer) - the total number of order clicks (the sum of clicks for all line items of this order) expected to be shown on day specified in the <date> element.
  • Zones:
  • zone:
id - (integer) the ID of the zone that the order's line items are expected to be shown on.
name - (string) the name of the zone.
impressions - (integer) the total number of the order impressions (the sum of impressions for all line items of this order) for that zone expected on day specified in the <date> element.
clicks - (integer) the total number of the order clicks (the sum of clicks for all line items of this order) for that zone expected on day specified in the <date> element.
The number of <zone> elements corresponds to the number of zones that the order's line items are to be shown on.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

getInventoryAdDetails()

Returns inventory forecasting report for a certain ad broken down by zones and days of the specified date range.

Parameters:

Parameter Type Description Required?
privatekey string The unique identifier generated for Mocean registered users to be able to use REST API functionality. required
ad_id integerThe ID of the line item to get the inventory forecasting for.required
start_date string The start date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the current date will be used as a start date.optional
end_date string The end date of the reporting range being accessed. The format is YYYY-MM-DD. If not specified, the report will be generated up to the end of the default forecasting period (1 year at the moment).optional

Request Sample:

Here is an example of HTTP request below. Do not forget to replace ’key_value’ with your real private key value and specify your real line item ID you want to get a forecasting information for.

Optionally, you can specify a certain period in future to generate a forecasting report for. Otherwise, you will get the report generated for a 1 year from the current moment.

http://moceanmobile.com/mocean_rest_server.php?method=getInventoryAdDetails&privatekey=key_value_here&ad_id=11419&start_date=2011-08-01&end_date=2011-08-20

Successful Response:

<xml>
<inventory>
<date>DATE</date>
<zones>
<zone>
<id>ZONE_ID</id>
<name>ZONE_NAME</name>
<impressions>IMPRESSIONS_NUMBER_FOR_THE_ZONE</impressions>
<clicks>CLICKS_NUMBER_FOR_THE_ZONE</clicks>
</zone>
</zones>
<total_impressions>TOTAL_IMPRESSIONS_NUMBER</total_impressions>
<total_clicks>TOTAL_CLICKS_NUMBER</total_clicks>
</inventory>
</xml>

  • Inventory:
date - (string) a day of the specified date range. The format is YYYY-MM-DD.
zones: - (Zones) the list of zones that the ad is expected to be shown on.
total_impressions - (integer) the total number of ad impressions expected to be shown on day specified in the <date> element.
total_clicks - (integer) the total number of ad clicks expected to be shown on day specified in the <date> element.
  • Zones:
  • zone:
id - (integer) the ID of the zone that the ad is expected to be shown on.
name - (string) the name of the zone.
impressions - (integer) the total number of ad impressions for that zone expected on day specified in the <date> element.
clicks - (integer) the total number of ad clicks for that zone expected on day specified in the <date> element.
The number of <zone> elements corresponds to the number of zones that the ad (line item) is to be shown on.

The response will contain as many <inventory> elements as there are days in the specified date range.

Failure Response:

A failure response could be like this:

<xml>
<error>no stats</error>
</xml>

OR like this:

<login>
<error>API Key is Invalid.</error>
</login>

Personal tools