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