microsoft_export

POST /API/v2/microsoft_export

Exports report data to Microsoft OneDrive. Data is restricted by query parameters passed in POST arguments. See example.

Request body¶

slicer_name: the name of the report.
project_name: the name of the project.
split_by: an array of the key fields to split data by in the form of ["key_field1",...].
include_mappings(optional): defines whether key field value mappings are returned by the API request. The default value is 1 (mappings are returned) if only 1 key field is used in the split_by POST argument. The default value is 0 (mappings are not returned) if 2 or more key fields are used in the split_by POST argument.
include_total(optional): defines whether to display Total values in the exported file. Possible values: (0 - don't display Total values in the exported file, 1 - display Total values in the exported file). The default value is 0.
add_keys : the array of key fields to add. Format: ["key_field1", ... ].
email: an array of 1 - 20 email addresses in the form of ["email_address1",...].
start_date, end_date: the start/end of the date range to gather data for. Supported formats:
- Absolute dates: YYYY-MM-DD.
- Relative dates:
  - today, yesterday
  - - N d and - N days for the number of days since the current date, where N - any positive integer or zero.
  - - N m and - N months for the number of months since the current date, where N - any positive integer or zero.
  - - N m_first, - N months_first, - N m_last, and - N months_last for the first and the last day of the specified month correspondingly, where N - any positive integer or zero.
  - -N d_m_first, where N - any positive integer. The first day of the month matches the following date: current date + N days. Examples for the current date of 2021-10-12:
  Template Resulting start_date
  
  -15d_m_first 2021-09-01
  
  0d_m_first 2021-10-01
  
  15d_m_first 2021-10-01
  
  -100d_m_first 2021-07-01
  
  30d_m_first 2021-11-01
timezone (optional):time zone UTC offset in hours. Format: N, where N - any integer in the range of -12 <= N <= +12.
filters (optional): an array with the following structure:
- "name": "key_field",
- "case_insensitive": (optional), defines whether search should be case-insensitive. Possible values: (1 - case-insensitive, 0 - case-sensitive). The default value is 0.
- "search_mappings": (optional), defines whether the search should be performed in mappings. Possible values: (1 - search should be performed in both key field values and their mappings, 0 - search should be performed in key field values only). The default value is 0.
- "value": ["value1", ... ],
- "match": "equals|not equals|contains|not contains|beginswith|endswith|not beginswith|not endswith"
where the value of the "value" field should be an array.

If "search_mappings" is set to 1, the search will be performed for both specified key field values and their mappings (descriptions). For example, if you have the creative_id key field with some value of "1" and its mapping of "First Creative", you can search for it as follows:

{"name": "creative_id", "value": ["First Creative"],"match":"equals", "search_mappings": 1}

OR

{"name": "creative_id", "value": [1],"match": "equals"}

Search results will be fully identical.

You can even use a partial matching, like {"name":"creative_id","value": ["Creative"],"match":" contains", "search_mappings": 1}, but please note that if you use a too short search string (1 - 2 characters long), it may take significant time to look up all matching records.
data_filters(optional): an array with the following structure:
- "name": "data_field",
- "value": "value1",
- "match": "<|>|<=|>=”
where the "value" field is just one value. The "match" can be "<" for less than value, ">" for greater than value, "<=" for less than or equal to value, or ">=" for greater than or equal to value.

If a data_field is in percent format, its value should also be divided by one hundred (30% becomes 0.3). Note, that this behavior is different in API and UI.
filter_template(optional): a string template defining priorities for filters specified in the filters POST argument. Can contain the following elements:
- opening/closing parentheses
- OR/AND operators
- "x" character as a placeholder for filters
Example: "x OR (x AND x)".

Filters from the filters POST argument in the specified order are substituted instead of x.
data_filter_template(optional): a string template defining priorities for filters specified in the data_filters POST argument. Can contain the following elements:
- opening/closing parentheses
- OR/AND operators
- "x" character as a placeholder for filters
Example: "x OR (x AND x)".

Filters from the data_filters POST argument in the specified order are substituted instead of x.
order_by (optional): defines sorting rules. A single record or an array of records with the following structure:
- "name": "field", the name of the key or data field to sort the results by. Note that this field can be any key field, specified in the split_by POST argument, or one of the data fields specified by the data_fields POST argument (or any of the data fields if the data_fields POST argument is not specified). The default value is the first column with enabled percent.
- "mapping": defines whether to sort by key field ID or by key field mapping. Possible values: (0 - sort by key field ID, 1 - sort by key field mapping). The default value is 0.
- "direction": sort in the ascending or descending order, either ASC or DESC. The default value is DESC.
data_fields (optional): the array of data fields to be returned in the form of [ "data_field1", .... ]. If it is not defined (by default), data fields will not be returned. To receive the details of all data fields available for your particular report use the info method.
data_field_options (optional): An array of objects used to specify additional query parameters for individual data fields. Each object supports the following structure:
- "name": "data_field": The name of the data field to which the options apply
- "currency_conversion": An object defining currency conversion parameters. Structure:
  - "currency_from": The source currency code (ISO 4217) of the data field (e.g., "USD"). The default currency can be retrieved from the info method via the default_currency property.
  - "currency_to": The target currency code (e.g., "EUR").
  - "mode: Currently, the only supported value is "daily". In this mode, the conversion rate is applied separately for each day within the requested interval, ensuring the highest level of accuracy. Every day conversion rate corresponding to that day will be taken
Example:
```
"data_fields": ["imps", "media_cost"],
"data_field_options": [
  {
    "name": "media_cost",
    "currency_conversion": {
      "currency_from": "USD",
      "currency_to": "EUR",
      "mode": "daily"
    }
  }
]
```
⚠️ Note:
The header in exported files will be changed depending on specified currency.
Example: "Media Cost, USD" or "Media Cost, JPY"
drive_folder (optional): Any folder in your Google Drive. Could be a shared folder as well. You can also use subfolders, e.g: Folder/SubFolder/SubSubFolder. Might be left empty.
drive_file_name: Any filename supported by Microsoft OneDrive. It is expected that filename ends with .xlsx.
can_write : Gives edit rights for users that you share the file with. Possible values: true and false. The default value is true.

Response¶

status: the status of the request. success, if the request was processed successfully, or error code, if any error occurred. If the status is not success**, then the response contains the status and reason fields only. Possible values:
- success: the request was processed successfully.
- bad_request: invalid request parameters, please see the reason field for more details.
- timeout: the request took too long to complete.
- access_error: the user doesn't have access to the specified project/slicer, or a wrong token was used.
- internal_error: the request failed due to an unknown problem.
reason: user-friendly description of the occurred error. This field is displayed for failed requests only.
Microsoft OneDrive file: a file with exported report data (column headers and data rows). Maximum 1048570 data rows.

Example¶

Export to Microsoft OneDrive a Report on all Campaigns, containing the "100" string, displayed in California and Texas to users of the Opera internet browser for the period from March 01, 2012 to March 03, 2012.

Path:

https://uslicer.iponweb.com/API/v2/microsoft_export

Request

JSONcurl

{
"slicer_name": "Traffic Demo",
"project_name": "demo",
"split_by": "campaign_id",
"start_date": "2011-02-16",
"end_date": "2011-02-18",
"email": [
  "jsmith@gmail.com"
  ]
"filters" : [
      {
        "name": "geo_region",
        "value": [
          "California",
          "Texas"
        ],
        "match": "equals"
      },
      {
        "name": "campaign_id",
        "value": [
            "100"
        ],
        "match": "contains"
      },
      {
        "name" : "browser",
        "value": [
            "Opera"
        ],
        "match" : "equals"
      }
  ]
}

curl --data '{
  "slicer_name": "Traffic Demo",
  "project_name": "demo",
  "split_by": "campaign_id",
  "start_date": "2012-03-01",
  "end_date": "2012-03-03", 
  "email": [
    "jsmith@gmail.com"
  ],
  "filters": [
    {
      "name": "geo_region", 
      "value":[
        "California",
        "Texas"
      ],
      "match": "equals"
    },
    {
      "name": "campaign_id",
      "value" :[
        "100"
      ],
      "match": "contains"
    },
    {
      "name": "browser", 
      "value":[
        "Opera"
      ], 
      "match": "equals"
    } 
  ], "drive_folder": "uSlicer export/",

   "drive_filename": "1.xslx" 
   }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  "https://uslicer.iponweb.com/API/v2/microsoft_export"

Response

JSON

{
  "status" : "success"
}

Template	Resulting start_date
`-15d_m_first`	2021-09-01
`0d_m_first`	2021-10-01
`15d_m_first`	2021-10-01
`-100d_m_first`	2021-07-01
`30d_m_first`	2021-11-01