Querying

Introductionback to top

Requests are made to the Data WareHouse using the GET method of the HTTP protocol. The default response format is XML, although JSON and CSV are also supported.

All requests require your clientId. You can find your clientId under the Account Profile section when you login to your GPN account.

The following endpoints are supported:

  • campaignActivity - Retrieve data associated with your ads or links.
  • order - Retrieve data associated with your sales.
  • ledger - Retrieve data related to your commission and invoices.

URL Constructionback to top

  • EndPoint
    Either campaignActivity, order or ledger depending on the data you are trying to access.
  • Client Id
    All requests require your clientId. You can find your clientId under the Account Profile section when you log in to to your GPN account.
  • Grouping
    Any combination of the dimensions supported by the endpoint. At least one dimension must be chosen.
  • Filters
    At least one date range filter must supplied.
  • Sorting
    The results returned from a query may be sorted in ascending or descending order.
  • Timezone
    Refer to section on timezone for sample requests.
  • Pagination
    The results may be paged.

Sample Responseback to top

Sample Response

In this example we are querying the order endpoint and grouping on the dimension date. We apply a date filter for the month of April. We append the '.json' to end endpoint to retrieve the data in JSON format.

The response is composed of the following fields:

  • total
    The total number of records found.
  • Summary
    The total for each of the measures associated with the endpoint. Each endpoint has its own set of measures.
  • Grouping
    A list of the dimensions used in the request.
  • Records
    The records array consists of the following object fields
    • group
      An array of dimension information. In this example, the information available on the date dimension.
    • Measures
      The total of the measures associated with the record.

Grouping Dimensionsback to top

For each of the endpoints grouping is mandatory. The grouping is specified by using the keyword 'group' as key in the query parameter

The api allows the user to make grouping on every available dimension or information. It allows also to group on multiple levels. To that purpose, use | to join groupings of information.

General Format

group=dimension1.information|dimension2.information

Sample Requests

Retrieve all link data for the year 2014 using the dimension campaign and information name, filtered by GBP currency.

https://partner-int-api.groupon.com/reporting/v2/campaignActivityV3.json?clientId=0a1f0db1ba5f4ab4d54e8c1aefebfa641ff3e75f&group=campaign.name&date=[2014-01-01&date=2014-12-31]&campaign.currency=GBP

Retrieve all order data for the year 2014 using dimensions order, campaign and deal, filtered by GBP currency. This shows all orders for the year 2014 by campaign and permalink.

https://partner-int-api.groupon.com/reporting/v2/order.json?clientId=0a1f0db1ba5f4ab4d54e8c1aefebfa641ff3e75f&group=order|campaign|deal&date=[2014-01-01&date=2014-12-31]&campaign.currency=GBP

Filteringback to top

Filters are composed by combining the information available on dimensions. Filters are combined by using the & operator. If you have sales in more than one currency, it is recommended that you add a currency filter to the API call.

Supported filtering operators
Operator Meaning Example
= equals Retrieve all link date for a date e.g.
date=2014-04-01
=! not equals Retrieve all link data except that of France e.g.
campaign.country=!FR
=] greater than Retrieve all link data after a date e.g.
date=]2014-04-01
=[ greater than or equal to Retrieve all link data after a date but include the date e.g.
date=[2014-04-01
=value[ less than Retrieve all link data before a date e.g.
date=2014-04-01[
=value] less than or equal to Retrieve all link data before a date but include the date e.g.
date=2014-04-01]
* like (only for String) Retrieve all link data with link name like 'shopping' e.g.
campaign.name=shopping*
!* not like (only for String) Retrieve all link data with link name not like 'shopping' e.g.
campaign.name=!shopping*

Sample Requests

Retrieve all link data for the year 2014 inclusive of the first and last day of the month, filtered by GBP currency.

https://partner-int-api.groupon.com/reporting/v2/campaignActivityV3.json?clientId=0a1f0db1ba5f4ab4d54e8c1aefebfa641ff3e75f&group=date&date=[2014-01-01&date=2014-12-31]&campaign.currency=GBP

Sortingback to top

The endpoints allow you to sort the results on the available dimensions, information or measures. The usage of the character '-' before a sorting criteria, will reverse the order of the result for the query.

Paginationback to top

The endpoints support paging of results.

  • pageSize - The number of records returned per page of results
  • page - The page number (starts from 1)

Timezoneback to top

The endpoints support paging of switching between timezones.

Refer to section on timezone for sample requests