MOLOCO Cloud Developer Portal

The MOLOCO Cloud Developer Hub

Welcome to the MOLOCO Cloud Developer Hub. You'll find comprehensive guides and documentation to help you start working with MOLOCO Cloud as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Report API

What is the MOLOCO Cloud Report API

MOLOCO Cloud Report API provides customers with a comprehensive set of APIs to create reports about MOLOCO Cloud campaigns.

  • Create / Read / List / Delete reports. Conceptually, a 'report' is a group of parameters that will be used to create a report. The parameters include ad account ID, start and end date, and dimensions. A dimension is a break-down condition for the metric numbers. For example, let's say you provided 'APP_OR_SITE' as a dimension. Then the metric numbers will be grouped by per each app or site that belongs to the given ad account.
  • Read report status. Whenever a new report is created, a designated report generation job is created. What the job does is to publish the report to a location where customers can retrieve the actual report files. By calling this API, you can check the status of the job and see where you can download the report files. Currently, the reports files are in two different formats: CSV and JSON.

Usage example: Create a Report

Creating a report is as simple as providing several parameters such as (1) your ad account ID, (2) date range for your report, and (3) the dimensions for your report break-down conditions.

$ cat report.json
{
  "ad_account_id": "$AD_ACCOUNT_ID",
  "date_range": {
    "start": "2019-01-02",
    "end": "2019-01-02"
  },
  "dimensions": [
    "DATE",
    "APP_OR_SITE",
    "CAMPAIGN",
    "AD_GROUP",
    "CREATIVE_GROUP",
    "CREATIVE",
    "EXCHANGE",
    "SUB_PUBLISHER",
    "TRAFFIC"
  ]
}

$ curl -X POST \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d "@report.json" \ https://api.moloco.cloud/cm/v1/reports 

{
  "id": "$REPORT_ID",
  "href": "https://api.moloco.cloud/cm/v1/reports/$REPORT_ID",
  "status": "https://api.moloco.cloud/cm/v1/reports/$REPORT_ID/status"
}

In this example, your report generation parameters are in the report.json file and delivered to the Report Creation API as an HTTP POST request body. Please change $AD_ACCOUNT_ID with the real ad account ID.

In the request response, you can find various information such as (1) your report ID ($REPORT_ID), (2) the location where your report creation input is stored (href), and (3) the URL that you can check the status of the actual report generation job (status).

In most cases, what you want to do after calling the Report Creation API is to access the URI returned in the status field because probably you want to see the actual report.

About the $ID_TOKEN, please see the "Getting Started with AdCloud API". In the "Prerequisite" section, you can find the information to retrieve $ID_TOKEN for the MOLOCO Cloud authentication.

Usage example: Access a Report

Access the report is as simple as calling the URI endpoint returned in status field in the body of the Report Creation API call result.

$ curl \
  -H "Authorization: Bearer $ID_TOKEN" \
  -H "Content-Type: application/json" \
https://api.moloco.cloud/cm/v1/reports/$REPORT_ID/status

{
  "status": "READY",
  "location_json": "https://$REPORT_STORAGE/$REPORT_ID.json",
  "location_csv": "https://$REPORT_STORAGE/$REPORT_ID.csv",
}

In the above example response body, you can find that there are 2 different report files provided for your convenience: (1) CSV, and (2) JSON.

Once the value of the field status is changed into READY as in the example, you can download the report files from the location given in location_json and location_csv.

The value of $REPORT_STORAGE is subject to change, thus you shouldn't write any logics depending on the value.

Schema of JSON file

The JSON report file conforms to the following JSON schema.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "description": "Contents of a report JSON file consisting of rows.",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Row"
      },
      "description": "Rows of the report."
    }
  },
  "definitions": {
    "Row": {
      "type": "object",
      "description": "A row in the report table consisting of columns.",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in \"yyyy-mm-dd\" format."
        },
        "ad_account": {
          "$ref": "#/definitions/AdAccountColumn",
          "description": "AdAccount column."
        },
        "app": {
          "$ref": "#/definitions/AppColumn",
          "description": "App column."
        },
        "site": {
          "$ref": "#/definitions/SiteColumn",
          "description": "Site column."
        },
        "campaign": {
          "$ref": "#/definitions/CampaignColumn",
          "description": "Campaign column."
        },
        "ad_group": {
          "$ref": "#/definitions/AdGroupColumn",
          "description": "Ad-group column."
        },
        "creative_group": {
          "$ref": "#/definitions/CreativeGroupColumn",
          "description": "Creative-group column."
        },
        "creative": {
          "$ref": "#/definitions/CreativeColumn",
          "description": "Creative column."
        },
        "exchange": {
          "$ref": "#/definitions/ExchangeColumn",
          "description": "Exchange column."
        },
        "sub_publisher": {
          "$ref": "#/definitions/SubPublisherColumn",
          "description": "Sub-publisher column."
        },
        "traffic": {
          "$ref": "#/definitions/TrafficColumn",
          "description": "Traffic column."
        },
        "metric": {
          "$ref": "#/definitions/MetricColumn",
          "description": "Metric column."
        },
        "skan": {
          "$ref": "#/definitions/SKANColumn",
          "description": "SKAN column."
        },
        "skan_metric": {
          "$ref": "#/definitions/SKANMetricColumn",
          "description": "SKAN Metric column."
        }
      }
    },
    "AdAccountColumn": {
      "type": "object",
      "description": "AdAccountColumn represents a structured column containing ad-account information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an ad-account."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an ad-account."
        },
        "currency": {
          "type": "string",
          "description": "Contract currency in ISO-4217."
        }
      }
    },
    "AppColumn": {
      "type": "object",
      "description": "AppColumn represents a structured column containing app information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an App."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an App."
        },
        "store_id": {
          "type": "string",
          "description": "ID of an App in the store."
        },
        "os": {
          "type": "string",
          "description": "OS type of an App."
        }
      }
    },
    "SiteColumn": {
      "type": "object",
      "description": "SiteColumn represents a structured column containing site information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a Site."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a Site."
        },
        "domain": {
          "type": "string",
          "description": "Domain of a Site."
        }
      }
    },
    "CampaignColumn": {
      "type": "object",
      "description": "CampaignColumn represents a structured column containing campaign information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a campaign."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a campaign."
        },
        "country": {
          "type": "string",
          "description": "Country code in ISO-3166 Alpha-3."
        }
      }
    },
    "AdGroupColumn": {
      "type": "object",
      "description": "AdGroupColumn represents a structured column containing ad-group information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an ad-group."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of an ad-group."
        }
      }
    },
    "CreativeGroupColumn": {
      "type": "object",
      "description": "CreativeGroupColumn represents a structured column containing creative-group information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a creative-group."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a creative-group."
        }
      }
    },
    "CreativeColumn": {
      "type": "object",
      "description": "CreativeColumn represents a structured column containing creative information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a creative."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a creative."
        },
        "type": {
          "type": "string",
          "description": "Type of a creative."
        },
        "main_asset_location": {
          "type": "string",
          "description": "URL of the main asset of a creative."
        }
      }
    },
    "ExchangeColumn": {
      "type": "object",
      "description": "ExchangeColumn represents a structured column containing ad-exchange information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of an exchange."
        }
      }
    },
    "SubPublisherColumn": {
      "type": "object",
      "description": "SubPublisherColumn represents a structured column containing sub-publisher information.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique ID of a sub-publisher."
        },
        "title": {
          "type": "string",
          "description": "Descriptive name of a sub-publisher."
        }
      }
    },
    "TrafficColumn": {
      "type": "object",
      "description": "TrafficColumn represents a structured column containing traffic information.",
      "properties": {
        "is_lat": {
          "type": "boolean",
          "description": "Flag indicating whether the bid was served with is_lat on or not."
        },
        "skan_bid": {
          "type": "boolean",
          "description": "Flag indicating whether the bid of the traffic includes a bid response for SK AdNetwork."
        },
        "mmp_effective": {
          "type": "boolean",
          "description": "Flag indicating whether the conversions from the bid can be attributed by MMP."
        }
      }
    },
    "MetricColumn": {
      "type": "object",
      "description": "MetricColumn represents a structured column containing metric numbers.",
      "properties": {
        "impressions": {
          "type": "string",
          "format": "int64",
          "description": "The number of impressions."
        },
        "clicks": {
          "type": "string",
          "format": "int64",
          "description": "The number of clicks."
        },
        "installs": {
          "type": "string",
          "format": "int64",
          "description": "The number of installs."
        },
        "spend": {
          "type": "number",
          "format": "double",
          "description": "The amount of ad spend in contract currency."
        },
        "revenue": {
          "type": "number",
          "format": "double",
          "description": "The amount of revenue in contract currency."
        }
      }
    },
    "SKANColumn": {
      "type": "object",
      "description": "SKANColumn represents a structured column containing SK AdNetwork  information.",
      "properties": {
        "conversion_value": {
          "type": "string",
          "description": "Conversion Value sent by Apple through SK AdNetwork postback."
        }
      }
    },
    "SKANMetricColumn": {
      "type": "object",
      "description": "SKANMetricColumn represents a structured column containing metric numbers related to SK AdNetwork information.",
      "properties": {
        "conversion_count": {
          "type": "string",
          "format": "int64",
          "description": "The number of counts associated with the corresponding conversion_value."
        }
      }
    }
  }
}

Updated 2 months ago


Report API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.