Heyzap Advertiser Reporting API

The Advertiser API contains information about your ad campaigns. You can fetch a campaign's clicks, installs, impressions, costs or get the device IDs (IDFAs or otherwise) of devices that have downloaded your app.

A key parameter is required for identification. This parameter can be retrieved by visiting the Advertiser API link that is at the bottom of the side-bar in the Campaigns section of the developer dashboard ().

You can explore and traverse your campaigns from the root of the Advertiser API.

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

Optionally pass along an app package to this endpoint to retrieve a list of links to the app's campaigns. If you have three campaigns associated with an app you'll receive three campaigns in the list.

Request:

curl --get http://developers.heyzap.com/api/campaigns/ \
  --data package=YOUR-APP-PACKAGE-HERE

Response:

{
  ...
  campaigns: [
    "http://developers.heyzap.com/api/campaigns/<ID-ONE> ...",
    "http://developers.heyzap.com/api/campaigns/<ID-TWO> ...",
    "http://developers.heyzap.com/api/campaigns/<ID-THREE> ...",
  ]
}

Campaign Details

Example: http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID

Returns the extended information of a given campaign. You can retrieve this information using the campaign id.

http://developers.heyzap.com/api/campaigns/:id

Request:

curl --get http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID \
  --data key=YOUR-KEY-ID

Response:

{
  campaign: {
    cpi: 46,
    enabled: true,
    title: "Test Campaign",
    id: 30,
    stats_url: "http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/stats?key=YOUR-KEY-ID",
    device_ids_url: "http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/device_ids?key=YOUR-KEY-ID"
  },
  status: 200
}

Campaign Stats

Example: http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/stats

Returns the number of installs, clicks, impressions, and costs of the campaign.

http://developers.heyzap.com/api/campaigns/:id/stats

The supported parameters are startdate and enddate. Dates need to be in the format: "2013-01-21", for January 21, 2013. If these dates are left off then today's date is used as both the start and end date. You can optinally add the parameter group_by_creative=true to group your stats by creative name. This endpoint can return CSV output by sending the parameter format with value csv.

Request:

curl --get http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/stats \
  --data key=YOUR-KEY-ID \
  --data start_date=2013-03-19 \
  --data end_date=2013-03-21

Response:

{
  days: [
    {
      app_installs: 41,
      total_installs: 284,
      total_cost: 321.33,
      ad_installs: 243,
      ad_impressions: 72849,
      ad_clicks: 6294,
      timestamp: 1363651200,
      date: "2013-03-19"
    },
    {
      ...
      date: "2013-03-20"
    },
    {
      ...
      date: "2013-03-21"
    },
  ],
  status: 200
}

The results for all the campaigns for an app can be retrieved with the following format:

Request:

curl --get http://developers.heyzap.com/api/campaigns/stats \
  --data key=YOUR-KEY-ID \
  --data start_date=2013-03-19 \
  --data end_date=2013-03-21 \
  --data package=YOUR-APP-PACKAGE

Response:

{
  campaigns: {
    CAMPAIGN-ID: [
      {
        app_installs: 41,
        total_installs: 284,
        total_cost: 321.33,
        ad_installs: 243,
        ad_impressions: 72849,
        ad_clicks: 6294,
        timestamp: 1363651200,
        date: "2013-03-19"
      },
      {
        ...
        date: "2013-03-20"
      },
      {
        ...
        date: "2013-03-21"
      },
    ]
  },
  status: 200
}

To get all the campaigns for a specific app include the app package as a parameter named package, to get all the campaigns for your apps don't include the package parameter.

Request:

curl --get http://developers.heyzap.com/api/campaigns/stats \
  --data key=YOUR-KEY-ID \
  --data start_date=2013-03-19 \
  --data end_date=2013-03-21

Response:

{
  results: {
    APP-PACKAGE-OR-APP-STORE-ID: {
      CAMPAIGN-ID: [
        {
          app_installs: 41,
          total_installs: 284,
          total_cost: 321.33,
          ad_installs: 243,
          ad_impressions: 72849,
          ad_clicks: 6294,
          timestamp: 1363651200,
          date: "2013-03-19"
        },
        {
          ...
          date: "2013-03-20"
        },
        {
          ...
          date: "2013-03-21"
        },
      ]
    }
  },
  status: 200
}

Campaign Device IDs

Example: http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/device_ids

Returns a list of device IDs for devices that have installed the app. For iPhone apps the device IDs are MAC addresses and for Android apps they are Android IDs.

http://developers.heyzap.com/api/campaigns/:id/device_ids

The device_ids endpoint accepts a single date parameter. The date needs to be in the format: "2013-01-21", for January 21, 2013. If this date is left off then today's date is used. This endpoint can return CSV output by sending the parameter format with value csv.

Request:

curl --get http://developers.heyzap.com/api/campaigns/YOUR-CAMPAIGN-ID/device_ids \
  --data key=YOUR-KEY-ID \
  --data date=2013-03-16

Response:

{
  days: [
    {
      timestamp: 1363392000,
      date: "2013-03-16",
      device_ids: [
        "00:88:65:59:2B:3D",
        "04:15:52:23:CF:27",
        "64:A3:CB:1F:1C:DA",
        "CC:78:5F:DB:55:92"
      ]
    }
  ],
  status: 200
}

The results for all the campaigns for an app can be retrieved with the following format:

http://developers.heyzap.com/api/campaigns/device_ids

Request:

curl --get http://developers.heyzap.com/api/campaigns/device_ids \
  --data key=YOUR-KEY-ID \
  --data date=2013-03-16
  --data package=YOUR-APP-PACKAGE

Response:

{
  campaigns: {
    CAMPAIGN-ID: {
      days: [
        {
          app_installs: 41,
          total_installs: 284,
          total_cost: 321.33,
          ad_installs: 243,
          ad_impressions: 72849,
          ad_clicks: 6294,
          timestamp: 1363651200,
          date: "2013-03-19"
        },
        {
          ...
          date: "2013-03-20"
        },
        {
          ...
          date: "2013-03-21"
        },
      ],
    }
  },
  status: 200
}

For Developer API, click here.