Heyzap Developer Reporting API

The Developer API contains information about the ads you are displaying through Heyzap. You can fetch the number of impressions, clicks, installs, and revenue per day for any app you are displaying ads in for a specified date range.

A key parameter is required for authenticating an API request. The value for this parameter can be found under API Key in your Account. Everywhere you see YOUR_KEY_ID below, replace this placeholder text with your own key.

You can start your search in the browser at the root of the Developer API.

curl -i http://developers.heyzap.com/api/publisher/

Publisher Details - All apps

Example: http://developers.heyzap.com/api/publisher/PUB_USERNAME

Returns stats on every app you are displaying ads in. You can browse this API using your publisher username:

http://developers.heyzap.com/api/publisher/:publisher_username

Request:

curl -L --get http://developers.heyzap.com/api/publisher/PUB_USERNAME \
--data key=YOUR_KEY_ID
--data start_date=2013-05-28

Response:

{
  game_data: {
    - 2013-05-28:{
        - 27: {
            impressions: 150,
            clicks: 37,
            installs: 9,
            revenue_in_cents: 450,
            cpm: 30,
            ctr: 0.24667,
            cvr: 0.06,
            url: "http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename?key=YOUR_KEY_IDstart_date=2013-05-29&end_date=2013_05_29",
            game_identifier: "com.fake.packagename",
            game_name: "Awesome Game",
            game_platform: "android"
        },
        - 139: {
            impressions: 1200,
            clicks: 193,
            installs: 36,
            revenue_in_cents: 1800,
            cpm: 15,
            ctr: 0.16083,
            cvr: 0.03,
            url: "http://developers.heyzap.com/api/publisher/PUB_USERNAME/ios/123456789?key=YOUR_KEY_ID&start_date=2013-05-29&end_date=2013_05_29",
            game_identifier: "123456789",
            game_name: "The Best Game Ever",
            game_platform: "ios"
        }
    },
    - 2013-05-29:{
        ...
    }

  },
  start_date: "2013-05-28",
  end_date: "2013-05-29"
}

The number that starts each app hash per day is a unique identifier we use in the backend for each app. No need to worry about it!

Note the start and end date parameters in the URL. You can modify these (keep the YYYY-MM-DD format) as you need!

curl -L was used to follow redirects. The API automatically redirects requests without dates specified to a URL with today's date (UTC) for start and end dates. In this example, the end date was automatically set to "today," which was 2013-05-29 at the time of writing.

Developer Details - One app only

Example: http://developers.heyzap.com/api/publisher/PUB_USERNAME/PLATFORM/APP_IDENTIFIER/

Returns the number of impressions, clicks, installs, and total revenue for one game on a range of dates.

Note: the APP_IDENTIFIER / :app_identifier is either your Android app's package string or your iOS app's App Store ID.

:platform should be set to either android or ios, depending on your app's platform.

http://developers.heyzap.com/api/publisher/:publisher_username/:platform/:app_identifier/

The supported parameters are startdate, enddate and ad_tag. Dates need to be in the format: "2013-05-29", for May 29, 2013. If these dates are left off then today's date is used as both the start and end date (in UTC).

Request:

curl --get http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename \
  --data key=YOUR_KEY_ID \
  --data start_date=2013-05-27 \
  --data end_date=2013-05-29
  --data ad_tag=loading_screen

Response:

{
    game_identifier: "com.fake.packagename",
    game_name: "Greatest Fake Game Ever!",
    game_platform: "android",
    game_data: {
        2013-05-27: {
            impressions: 2000,
            clicks: 937,
            installs: 410,
            revenue_in_cents: 2050,
            cpm: 10.25,
            ctr: 0.4685,
            cvr: 0.205,
            url: "http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename?key=YOUR_KEY_ID&start_date=2013-05-27&end_date=2013-05-27"
        },
        2013-05-28: {
            ...
        },
        2013-05-29: {
            ...
        }
    },
    start_date: "2013-05-27",
    end_date: "2013-05-29"
}

Specifying Creative Type

Heyzap's SDK supports showing Interstitial, Video, and Rewarded-View ads. By default, the API will return data for all ad formats combined. You can segment by ad format by using the creative_type parameter, which accepts the following values: interstitial, video, and rewarded.

Request:

curl --get http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename \
  --data key=YOUR_KEY_ID \
  --data start_date=2013-05-28 \
  --data creative_type=rewarded

Response:

{
  "game_data": {
    "2014-05-01": {
      "3": {
        "impressions": 500,
        "clicks": 0,
        "installs": 0,
        "cvr": 0.0,
        "ctr": 0.0,
        "cpm": 0.0,
        "revenue_in_cents": 0,
        "revenue": 0.0,
        "game_identifier": APP_STORE_ID,
        "game_name": "Example Game",
        "game_platform": "iOS",
        "url": "http://developers.heyzap.com/api/publisher/PUB_USERNAME/ios/APP_STORE_ID/?key=YOUR_KEY&start_date=2013-05-28&end_date=2014-05-01"
      }
    }
  },
  "start_date": "2013-05-28",
  "end_date": "2014-05-06",
  "creative_type": "rewarded"
}

Specifying Ad Network

Heyzap's SDK will deliver ads from Heyzap's own ad nework, as well as Heyzap's Exchange network. By default, the API will return data for only the Heyzap Ad network. You may retrieve data for Heyzap Exchange, or both networks by using the network parameter, which accepts the following values: heyzap, heyzap_exchange and heyzap,heyzap_exchange. To specify

Request:

curl --get http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename \
  --data key=YOUR_KEY_ID \
  --data start_date=2013-05-28 \
  --data network=heyzap_exchange

Response:

{
  "game_data": {
    "2014-05-01": {
      "3": {
        "impressions": 900,
        "clicks": 0,
        "installs": 0,
        "cvr": 0.0,
        "ctr": 0.0,
        "cpm": 0.0,
        "revenue_in_cents": 0,
        "revenue": 0.0,
        "game_identifier": APP_STORE_ID,
        "game_name": "Example Game",
        "game_platform": "iOS",
        "url": "http://developers.heyzap.com/api/publisher/PUB_USERNAME/ios/APP_STORE_ID/?key=YOUR_KEY&start_date=2013-05-28&end_date=2014-05-01"
      }
    }
  },
  "start_date": "2013-05-28",
  "end_date": "2014-05-06",
}

CSV-Formatted Output

Anytime you are viewing data via the Publishers API, you may also download the data in CSV format instead of viewing it in JSON. This works when viewing all games, or just one game, and uses the same start/end date parameters as before.

All you need to do is add the format=csv parameter to your GET request:

Request:

curl --get http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename \
  --data key=YOUR_KEY_ID \
  --data start_date=2013-05-27 \
  --data end_date=2013-05-29
  --data format=csv

Response:

Date,Identifier,Name,Platform,Impressions,Clicks,Installs,Revenue (cents),CPM ($),CTR,CVR
2013-05-27,com.fake.packagename,Greatest Fake Game Ever!,android,2000,937,410,2050,10.25,0.4685,0.205
2013-05-28,...
2013-05-29,...

This also works from the browser (your .csv file will automatically start downloading):

http://developers.heyzap.com/api/publisher/PUB_USERNAME/android/com.fake.packagename?key=YOUR_KEY_ID&start_date=2013-05-27&end_date=2013-05-29&format=csv

For Advertiser API, click here.