Migration from Supermetrics API version 1 to version 2

This page will help you migrate from Supermetrics API version 1 (v1) queries into version 2 (v2).

For ease of readability, we will refer to the versions as "version v1" and "version v2". Such migration will be backwards incompatible. Therefore, please ensure you read carefully and are aware of the new features enabled with version v2.

Migration checklist

Note: If you prefer, you can also use the query conversion endpoint to turn your existing version v1 queries into version v2 queries.

Endpoint changes

In version v2 output format is no longer defined by the targetAppFormat parameter. Instead, each output format has its own dedicated endpoint.

JSON (default)
V1https://supermetrics.com/api/v1/getData
V2https://api.supermetrics.com/enterprise/v2/query/data/json
PowerBI
V1https://supermetrics.com/api/v1/getData?..&targetAppFormat=powerbi
V2https://api.supermetrics.com/enterprise/v2/query/data/powerbi
Qlik
V1https://supermetrics.com/api/v1/getData?..&targetAppFormat=qlik
V2https://api.supermetrics.com/enterprise/v2/query/data/qlik
Tableau
V1https://supermetrics.com/api/v1/getData?..&targetAppFormat=tableau
V2https://api.supermetrics.com/enterprise/v2/query/data/tableau

Changes to the request format

The most visible change in query parameters is how the parameters are sent with the request. You can now send them as a JSON string via the json parameter.

HTTP Postman examples 
GET /enterprise/v2/query/data/json?json={
    "api_key": "<api key>",
    "ds_id": "GA",
    "ds_accounts": "567890",
    "start_date": "2020-01-01",
    "end_date": "today",
    "fields": "date, impressions",
    "settings": {"no_headers":true},
    "filter": "impressions > 0 AND impressions < 100",
    "order_rows": "impressions desc,date desc",
    "max_rows": 1000
}

You can also still use traditional GET parameters, if that is what you prefer, or switch to POST method to make application/json requests.

Changes to the parameter format

Here you can see the difference between key query parameters. For more, see the full parameter list.

API key

V1?apiKey=<your api key>
V2?json={"api_key":"<your api key>"}

We recommend using an authorization header whenever possible.

Data source ID

V1?dataSource=GA
V2?json={"ds_id":"GA"}

Please verify that the data source you are using is already supported by version v2. If your data source is missing, let us know or contact your account representative.

Data source username

V1?dsUser=e_35681351584
V2?json={"ds_user":"e_35681351584"}

Data source username is no longer required but is recommended for improved performance.

Data source accounts

V1?profiles=[{"ID":"567890", "name":"Support"}, {"ID":"52348", "name":"Other"}]
V2?json={"ds_accounts":"567890,52348"}

Date range

V1?dateRangeType=custom&start-date=2020-01-01&end-date=today
V2?json={"date_range_type":"custom", "start_date":"2020-01-01", "end_date":"today"}

Please note that date range type values have changed.

Fields

V1?metrics=visits&dimensions=Year,EventAction
V2?json={"fields":"visits,Year,EventAction"}

Both metrics and dimensions are now combined into fields parameter.

Fields, split to columns

V1?metrics=visits&pdimensions=Source
V2?json={"fields":["visits", {"id":"Source", "split":"column"}]}

Settings

V1?settings=AVOID_SAMPLING,TIMEZONE_America/New_York
V2?json={"settings":{"avoid_sampling":true, "timezone":"America/New_York"}}

Settings are specified in key-value pairs. Please see supported settings.

Filter

V1?filters=CampaignName=~Super;CampaignName!=Superman
V2?json={"filter":"CampaignName =~ Super AND CampaignName != Superman"}}

Filter string now requires specific formatting and logical operator names.

Ordering

V1?sort=Year;2nd:EventAction_desc
V2?json={"order_rows":"Year asc,EventAction desc"}}

Changes to responses

Behaviour

  • API version v1 did not use HTTP status codes. In version v2 we will respond with HTTP status code 200 OK only for successful responses.

  • When the query is correct but no data is found, this will no longer be considered an "error". Response will contain data for 0 rows and HTTP status code is 200 OK.

  • Queries exceeding maximum wait time used to respond with 200 OK. This is now 202 Accepted. See async queries for more.

Content

Query response in version v2 contains two properties.

  • meta
    Information about the query and its response. If you rely on this information, please see the related documentation.

  • data
    Actual query data. There are no changes between version v1 and version v2 in the contents of this property.

Errors

Error responses in version v2 are formatted in the following way.

HTTP 401 Unauthorized
{
    "meta": {
        "request_id": "tDcBg85cRzVZru7mRVQNkQ35tE4DdsPu"
    },
    "error": {
        "code": "API_KEY_INVALID",
        "message": "Invalid API key",
        "description": "Provided API key was invalid."
    },
    "links": {
        "docs": {
            "href": "https://supermetrics.com/docs/product-api-error-codes#api_key_invalid"
        }
    }
}

Please see documented error codes and adjust your error handling accordingly.

Usage restrictions

Please read more about usage limits for queries. For detailed questions on how these might affect you, please contact us or ask your account representative.

Resources

→ Support options »

Last updated 2022-06-22 UTC.