NAV Navbar
shell
  • Getting Started
  • Authentication
  • Campaigns
  • Advertising Reports
  • Attribution Reports
  • 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.