Getting Started

The Gimbal Advertising API allows your application to track campaigns running on the Gimbal platform. In order to get started, you'll need an Access Token, which you may request from your Gimbal representative. Generally, we limit Gimbal Advertising API requests to report generation, but if your application requires deeper integration you may apply for an advanced Access Token.

To generate a report see the Reports documentation.

Our API follows JSON API specifications. For more info, see JSON API.

Authentication

Your Access Token should be sent with all requests in the headers as:

Authorization: Bearer {access_token}

Campaigns

Get a list of campaigns

Request

curl "http://partner-api.tmmp.io/v1/campaigns"
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/vnd.api+json"

Response

{
  "data": [
    {
      "id": "59a44aed8d3e210001276ac9",
      "type": "campaigns",
      "attributes": {
        "click-through-url": "https://my.landingpage.com",
        "created-at": "2016-11-01T00:00:00.000Z",
        "custom-rich-media": false,
        "description": "Sell more hamburgers!",
        "flight-ends-at": "2016-11-01T00:00:00.000Z",
        "flight-starts-at": "2016-10-01T00:00:00.000Z",
        "impression-goal": "50000",
        "name": "My First Campaign",
        "reporting-enabled": true,
        "submitter-email": "",
        "submitter-first-name": "",
        "submitter-last-name": "",
        "target-ages": [
          "13-18",
          "18-30",
          "30-45",
          "45-65",
          "65+"
        ],
        "target-description": "Soccer Dads",
        "target-gender": "Male",
        "target-household-incomes": [
          "0To30000",
          "30000To60000",
          "60000To80000",
          "80000To100000",
          "100000To125000",
          "125000To150000",
          "150000OrMore"
        ],
        "target-places": [
          {
            "id": "AVI8ehW6hhDeC7d236oz",
            "name": "Pittsburgh, PA"
          }
        ],
        "total-budget": 10000
      }
    }
  ]
}

This is an index of your campaigns. Here you can find information about the budget, flight dates (when the campaign should run), and the mobile audience of your campaign(s). Contact your Gimbal representative for more information.

HTTP Request

GET http://partner-api.tmmp.io/v1/campaigns

Response Attributes

Attribute	Type	Description
click-through-url	string	The campaign's click through URL.
created-at	string	The date and time in which the campaign was created (UTC formatted as ISO8601).
custom-rich-media	boolean	Whether or not you wish to traffic a custom rich media ad.
description	string	The advertising goal for this campaign.
flight-ends-at	string	The date and time the campaign should stop running (UTC formatted as ISO8601).
flight-starts-at	string	The date and time the campaign should start running (UTC formatted as ISO8601).
impression-goal	number	The target total number of impressions for the campaign.
name	string	The name of your campaign.
reporting-enabled	boolean	Whether or not live reporting for this campaign is enabled by your Account Manager.
submitter-email	string	The contact email of the person submitting the campaign.
submitter-first-name	string	The first name of the person submitting the campaign.
submitter-last-name	string	The last name of the person submitting the campaign.
target-ages	array	Age groups to target.
target-description	string	A description of your target audience.
target-gender	string	Gender to target. [`Male`, `Female`]
target-household-incomes	array	Income groups to target.
target-places	array	Places to target.
total-budget	number	The total budget for your campaign.

Advertising Reports

Create a advertising performance report for a campaign

Request

curl -X POST "http://partner-api.tmmp.io/v1/analytics/advertising/campaign-reports"
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/vnd.api+json"

{
  "data": {
    "attributes": {
      "starts_at": "2016-08-29T00:00:00.000Z",
      "ends_at": "2016-08-30:11:59.000Z",
    },
    "relationships": {
      "campaign": {
        "data": { "id": "59a44aed8d3e210001276ac9", type: "campaigns" }
      }
    }
  }
}

Response

{
  "data": [
    {
      "id": "59a44aed8d3e21000127ha27",
      "type": "advertising-campaign-reports",
      "attributes": {
        "name": "Example Campaign",
        "clicks": 0,
        "impressions": 0,
        "timeseries": [
          {
            "clicks": 0,
            "impressions": 0,
            "timestamp": "2016-08-29"
          }
        ]
      },
      "relationships": {
        "advertisement-report": {
          "data": {
            "id": "59a44aed8d3e210001276ac9",
            "type": "advertising-advertisement-reports"
          }
        },
        "placement-report": {
          "data": {
            "id": "59a44aed8d3e210001276ac1",
            "type": "advertising-placement-reports"
          }
        },
        "city-report": {
          "data": {
            "id": "59a44aed8d3e210001276ac2",
            "type": "advertising-city-reports"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "59a44aed8d3e210001276ac9",
      "type": "advertising-advertisement-reports",
      "attributes": {
        "name": "Example Advertisement",
        "clicks": 0,
        "impressions": 0,
        "ctr": 0,
        "timeseries": [
          {
            "clicks": 0,
            "impressions": 0,
            "timestamp": "2016-08-29"
          }
        ]
      }
    },
    {

      "id": "59a44aed8d3e210001276ac1",
      "type": "advertising-placement-reports",
      "attributes": {
        "name": "Example Placement",
        "clicks": 0,
        "impressions": 0,
        "ctr": 0
      }
    },
    {
      "id": "59a44aed8d3e210001276ac2",
      "type": "advertsing-city-reports",
      "attributes": {
        "name": "Example City",
        "clicks": 0,
        "impressions": 0,
        "ctr": 0
      }
    }
  ]
}

Request Attributes

Attribute	Type	Description
campaign.id	string, required	The campaign you want to generate a report for. Example: `59a44aed8d3e210001276ac9`.
starts-at	string, required	Select only results appearing after this date. Example: `2016-08-29T00:00:00.000Z`.
ends-at	string, required	Select only results appearing before this date. Example: `2016-08-29T00:00:00.000Z`.

Response Attributes

Attribute	Type	Description
clicks	number	The total number of clicks tracked (within date range if provided).
impressions	number	The total number of impressions tracked (within date range if provided).
ctr	number	The click through rate based on impressions and clicks.
timeseries	array	The campaign metrics broken down by day (within date range if provided).
timeseries[].clicks	number	The total number of clicks tracked for the date.
timeseries[].impressions	number	The total number of impressions tracked for the date.
timeseries[].ctr	number	The click through rate based on impressions and clicks.
timeseries[].timestamp	string	The timestamp of the timeseries point.

Attribution Reports

Create a attribution performance report for a campaign

Request

curl -X POST "http://partner-api.tmmp.io/v1/analytics/attribution/campaign-reports"
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/vnd.api+json"

{
  "data": {
    "attributes": {
      "starts_at": "2016-08-29T00:00:00.000Z",
      "ends_at": "2016-08-30:11:59.000Z",
      "minimum-dwell-time": 60,
      "maximum-dwell-time": 6000
    },
    "relationships": {
      "campaign": {
        "data": { "id": "59a44aed8d3e210001276ac9", type: "campaigns" }
      }
    }
  }
}

Response

{
  "data": [
    {
      "id": "59a44aed8d3e21000127ha27",
      "type": "attribution-campaign-reports",
      "attributes": {
        "total-visits": 10,
        "unique-visits": 7,
        "total-adjusted-dwell-time": 7000,
        "average-dwell-time": 500,
        "timeseries": [
          {
            "timestamp": "2016-08-29",
            "total-visits": 10,
            "unique-visits": 7,
            "total-adjusted-dwell-time": 7000,
            "average-dwell-time": 500
          }
        ]
      }
    }
  ]
}

Request Attributes

Attribute	Type	Description
campaign.id	string, required	The campaign you want to generate a report for. Example: `59a44aed8d3e210001276ac9`.
starts-at	string, required	Select only results appearing after this date. Example: `2016-08-29T00:00:00.000Z`.
ends-at	string, required	Select only results appearing before this date. Example: `2016-08-29T00:00:00.000Z`.
minimum-dwell-time	number	The minimum dwell time in seconds to consider a visit valid.
maximum-dwell-time	number	The maximum dwell time in seconds to consider a visit valid.

Response Attributes

Attribute	Type	Description
total-visits	number	The total number of attributed visits tracked (within date range).
unique-visits	number	The total number of unique visits tracked (during interval of date range).
average-dwell-time	number	The average amount of time in seconds of each visit
total-adjusted-dwell-time	number	The total amount of time in seconds of all visits
timeseries	array	The attribution metrics broken down by day (within date range if provided).
timeseries[].total-visits	number	The total number of attributed visits tracked for the date.
timeseries[].unique-visits	number	The total number of unique attributed visits tracked for the date.
timeseries[].average-dwell-time	number	The average amount of time in seconds of each visit on for this date.
timeseries[].total-adjusted-dwell-time	number	The total amount of time in seconds of all visits for this date.