Developer Reporting API V2

The FairBid Developer API V2 contains information about the ads you are displaying in your apps through FairBid. 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. In order to use the FairBid Developer API you will need to retrieve your API key. This can be found in the dashboard under Accounts / Account Details.

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 FairBid 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 FairBid 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 FairBid 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 FairBid 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.