Developer Reporting API V2

The Developer Reporting API V2 contains information about the ads you are displaying in your apps through Heyzap. You can fetch relevant daily stats (like impression/click counts, revenue, and eCPM) for any app you are displaying ads in for a specified date range. You can also filter this data by geo or ad network, and you can group it by ad network, format, geo, and app.

A key parameter is required for authenticating each API request. The value for this parameter is labeled API Key on your Account Details page. Everywhere you see YOUR_API_KEY below, replace this placeholder text with your own key.

All Apps - Information

Example: http://developers.heyzap.com/api/v2/publisher/applications?developer=username&key=YOUR_API_KEY

Returns information, dashboard URLs, and API URLs for every app under your account.

Required parameters:

  • developer: your Heyzap username
  • key: your API Key

Request:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications?developer=username&key=YOUR_API_KEY

Response:

{
  data: [
  {
      "app_id": "123",
      "app_name": "My App",
      "platform": "ios",
      "dashboard_url": "https://developers.heyzap.com/dashboard/publisher/revenue?game=123",
      "api_url": "https://developers.heyzap.com/api/v2/publisher/applications/stats?app_id=123&developer=heyzap&key=YOUR_API_KEY&start_date=2015-12-09&end_date=2015-12-16",
      "app_store_id": 1234567,
      "app_bundle_id": "com.heyzap.greatapp"
  },
  {
      "app_id": "124",
      "app_name": "My Second App",
      "platform": "amazon",
      "dashboard_url": "https://developers.heyzap.com/dashboard/publisher/revenue?game=124",
      "api_url": "https://developers.heyzap.com/api/v2/publisher/applications/stats?app_id=124&developer=heyzap&key=YOUR_API_KEY&start_date=2015-12-09&end_date=2015-12-16",
      "android_package": "com.heyzap.secondapp"
  },

  ...

  ]
}

(curl -L was used to follow redirects.)

All Apps - Stats

Example: http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&start_date=2015-06-18&end_date=2015-06-22

Returns aggragated impressions, revenue in cents and ecpm for all your apps on a range of dates.

Required parameters:

  • developer: your Heyzap username
  • key: your API Key
  • start_date and end_date: The date range for your request, in YYYY-MM-DD format.

Request:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&start_date=2015-06-18&end_date=2015-06-22

Response:

{
  "data": [
      {
          "app_name": "My App",
          "app_id": "123",
          "data": {
            "impressions": 5329,
            "revenue_in_cents": 60,
            "ecpm_cents": 11.25
          }
      },
      {
          "app_name": "My Second App",
          "app_id": "124",
          "data": {
            "impressions": 2140,
            "revenue_in_cents": 21,
            "ecpm_cents": 9.81
          }
      },

    ...

  ]
}

Single App Stats Using app_id

Example: http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=heyzap&app_id=123&start_date=2015-06-22&end_date=2015-06-28&key=API_KEY

Returns stats for one game on a range of dates.

Note: the app_id is your application's ID in our database, which can be found by requesting all app information first (see above).

Required parameters:

  • developer: your Heyzap username
  • key: your API Key
  • start_date and end_date: The date range for your request, in YYYY-MM-DD format.
  • app_id: The App ID for the specific app you wish to get stats for.

Request:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&start_date=2015-06-18&end_date=2015-06-22&app_id=123

Response:

{
    "stats": full,
    "aggregated_data": {
        "impressions": 100000,
        "revenue_in_cents": 10000,
        "clicks": 4000,
        "ecpm_cents": 1.00
    },
    "data": [
      {
        "date": "2015-06-18",
        "app_id": "123",
        "app_name": "My App",
        "network": "adcolony",
        "platform": "ios",
        "format": "video",
        "data": [
          {
            "country_code": "AD",
            "currency": "USD",
            "revenue_in_cents": 7,
            "impressions": 444,
            "clicks": 83,
            "ecpm_cents": 15.77
          },
          {
            "country_code": "AE",
            "currency": "USD",
            "revenue_in_cents": 116,
            "impressions": 21904,
            "clicks": 1024,
            "ecpm_cents": 5.29
          },

          ...

        ]
      },
      {
        "date": "2015-06-18",
        "app_id": "123",
        "app_name": "My App",
        "network": "admob",
        "platform": "ios",
        "format": "video",
        "data": [
          {
            ...
          },

          ... 

        ],
      },

      ...

    ]
}

Single App Stats Without Using app_id

Developer Reporting API V2 allows you to check app stats without using app_id. Instead, you can pass in and a App Store ID (iOS), bundle identifier (iOS), or Android package (Android/Amazon) to identify your app.

Required parameters:

  • developer: your Heyzap username
  • key: your API Key
  • start_date and end_date: The date range for your request, in YYYY-MM-DD format.
  • app_store_id or app_bundle_id or android_package: The relevant identifier for the specific app you wish to get stats for.

Note: If you want to retrieve stats for an Amazon app, you also need to pass the platform parameter and set it to amazon.

Example

Request:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&app_store_id=1234567

or

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&app_bundle_id=com.heyzap.greatapp

or

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&android_package=com.heyzap.greatapp

or

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats?developer=username&key=YOUR_API_KEY&android_package=com.heyzap.secondapp&platform=amazon

Filtering

The Developer Reporting API V2 supports filtering. You can pass in various filters by specifiying them in the query string.

Valid filters: geo and network

Example

Request:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats/?developer=username&key=YOUR_API_KEY&start_date=2015-06-20&end_date=2015-06-22&geo=us&network=heyzap

Response:

  {
        "stats" :full
        "aggregated_data": {
            "impressions": 100000,
            "revenue_in_cents": 10000,
            "clicks": 4000,
            "ecpm_cents": 1.00
        }
        "data": [
            {
              "data": "2015-06-18",
              "app_id": "123",
              "app_name": "My App",
              "network": "heyzap",
              "platform": "ios",
              "format": "video"
            },
            "data": [
              {
                "country_code": "US",
                "currency": "USD",
                "revenue_in_cents": 7,
                "impressions": 2222,
                "clicks": 207,
                "ecpm_cents": 3.15
              }
            ]
            {
              "data": "2015-06-19",
              "app_id": "123",
              "app_name": "My App",
              "network": "heyzap",
              "platform": "ios",
              "format": "video"
            },
            "data": [
              {
                "country_code": "US",
                "currency": "USD",
                "revenue_in_cents": 7,
                "impressions": 2222,                
                "clicks": 83,
                "ecpm_cents": 3.15
              }
            ]
            },
            ...
        ]
    }

Note: You can pass in multiple filters - the example above passed both geo=us and network=heyzap at the same time. Note: For each filter, you can pass in multiple values by seperating them with a comma.

Example:

curl -L --get http://developers.heyzap.com/api/v2/publisher/applications/stats/?app_id=123&key=YOUR_API_KEY&start_date=2015-06-20&end_date=2015-06-22&geo=us,gb&network=heyzap,admob

Grouping

The Developer Reporting API V2 supports one-dimensional grouping. You can specify a grouping in the query string with a paremeter named 'group_by'.

Valid grouping values: network, format, and country

Example:

Request:

curl --get http://developers.heyzap.com/api/v2/publisher/applications/stats/?developer=username&key=YOUR_API_KEY&app_id=12&start_date=2015-06-20&end_date=2015-06-22&group_by=network

Response:

{
    "stats": "full",
    "group_by": "network",
    "data": [
        {
            "ad_network": "adcolony",
            "impressions": 92843,
            "revenue_in_cents": 15304,
            "ecpm_cents": 17.05
        },
        {
            "ad_network": "applovin",
            "impressions": 4381,
            "revenue_in_cents": 512,
            "ecpm_cents": 13.0
        },
        {
            "ad_network": "chartboost",
            "impressions": 7380,
            "revenue_in_cents": 6647,
            "ecpm_cents": 9.03
        },
        {
            "ad_network": "heyzap",
            "impressions": 6508,
            "revenue_in_cents": 1639,
            "ecpm_cents": 2.51
        },
        {
           "ad_network": "unityads",
           "impressions": 20241,
           "revenue_in_cents": 19728,
           "ecpm_cents": 9.53
        }
    ]
}

Stats for Multiple Apps

The Developer Reporting API V2 supports multi-app queries. You can get stats for multiple apps that you own by passing a comma-separated list of app_ids via the app_id parameter.

Example:

curl --get http://developers.heyzap.com/api/v2/publisher/applications/stats/?developer=username&app_id=123,124&key=YOUR_API_KEY&start_date=2015-06-20&end_date=2015-06-22

For the Advertiser API, click here.