This documentation refers to the GWI API. It presents RESTful endpoints for all appropriate resources, as well as a query language to retrieve specific information.

In general, assume that GET requests will be used to read data, POST requests to create or filter data, PUT/PATCH to update data, and DELETE to remove data. Due to technical requirements, there is an exception to this: queries are made using POST requests, despite these actually being an attempt to read data.

The API endpoints reflect the nature of the GWI data offering. We run the world's largest market research study on the digital consumer, offering our clients a unique data set that enables strong strategic marketing and selling.

All the endpoints are listed below. To query an endpoint, the request structure is always the same - you just change the path between the API root and the resource identifier to request the data you are interested in.

Responses will be in JSON format, and will be served along with appropriate HTTP response codes. For example, 200 will indicate a generic success, 201 the creation of a new resource, 204 the successful deletion of a resource, 400 a malformed request, 401 for missing or broken authorization, 403 for inaccessible data, 404 a request for data that is not available, etc. For more details refer to List of HTTP Status Codes.

Each request to the API requires an authorization token. This identifies you as a GWI customer and also allows us to look up the access rights that were pre-configured for you.

To use the token, simply send it along with any request in Authorization header. Once you have the token, prepend it with Bearer followed by a space, so the field looks like this: Bearer YOUR_ACCESS_TOKEN. Then add that to the Authorization field in the headers, so that the RAW headers looks like this: Authorization: Bearer YOUR_ACCESS_TOKEN.

You can check if your token works properly by calling token validation endpoint.

Our system exposes a public API where requests made by clients can cause heavy load on our backend services. A rate limiting proxy is necessary to avoid DoS by API clients overloading our system by accident.

HTTP headers:

Retry-After - Try again after N seconds X-RateLimit-Limit - Total number of requests allowed within this time window X-RateLimit-Remaining - The number of requests left for the time window X-RateLimit-Reset - The remaining window before the rate limit resets in UTC epoch seconds

HTTP status codes:

500 request does not contain token 429 too many requests 400 bad request (wrong HTTP method, invalid payload) 200 ok

The general query used is called a Stats Query. However, to use it, you first need to call a few other endpoints to compose the Stats Query POST body. This will describe what data you are interested in.

Categories

Individual questions and datapoints for studies are grouped together into folders called categories. You can think of them as a tree of folders, where every category can contain subcategories or questions.

To retrieve root categories and their children, call categories endpoints:

POST /v2/categories/filter --data '{}'

{
  "categories": [
  {
      "id": "330",
      "name": "GWI Core"
    },
    {
      "id": "11338",
      "name": "GWI Sports",
      "order": 5
    },
    ...
  ]
}

We will use the categories[0].id from previous step to call the category detail endpoint and to load the details and children of root category 330:

GET /v2/categories/330?include=children

{
  "category": {
    "id": "330",
    "name": "GWI Core",
    "description": "Our primary data set on the attitudes and behaviors of digital consumers",
    "child_categories": [
        {
            "id": "340",
            "name": "Demographics",
            "order": 4
        },
        {
            "id": "415",
            "name": "Work & Professional Life",
            "order": 8
        },
        ...
    ]
  }
}

Call category detail endpoint recursively for each of child_categories, until you find child_questions:

GET /v2/categories/415?include=children

{
  "category": {
    "id": "415",
    "name": "Work & Professional Life",
    "child_questions": [
      {
        "code": "q14",
        "name": "Employment Status",
        "namespace_code": "core",
        "description": "What is your current working status?",
        "order": 10000,
        "attribute_count": 9
      },
      {
        "code": "q22019",
        "name": "Job Seniority",
        "namespace_code": "core",
        "description": "Which of these best describes your role?",
        "order": 10003,
        "attribute_count": 9
      },
      ...
    ]
  }
}

Basic Query

Now that you understand the basics of how to walk the categories tree and retrieve question details you can try to run a basic Stats Query:

POST /v2/query/stats --data '{"question": "q14"}'

{
  "meta": {
    "type": "DATAPOINTS",
    "question": "q14",
    "splitter": ""
  },
  "data": [
    {
      "datapoint": "q14_1",
      "waves": [
        "q4_2020",
        "q4_2021",
        ...
      ],
      "metrics": {
        "positive_sample": 2057166,
        "positive_size": 985811381,
        "audience_sample": 4117017,
        "audience_size": 1885022456,
        "audience_percentage": 52.3,
        "audience_index": 100,
        "datapoint_sample": 2057166,
        "datapoint_size": 985811381,
        "datapoint_percentage": 100
      }
    },
    ...
  ]
}

Calculations API supports additional filtering using waves, locations and datapoints. It is also possible to apply special question called splitter, so you can see your selected question, but segmented (split) into individual datapoints of the splitter question - for example age groups.

Question namespace

First thing we have to explain are namespaces. They are a group of questions and datapoints from a single study. Locations, Waves and Splitters are defined on the namespace level, so to find out which locations can be used with selected question, we need to use the question's namespace code. In the previous example, you can see how to retrieve category and its questions. That endpoint, however, is not showing all the detail. To view all of question including the description and all of its datapoints and suffixes, we call question detail endpoint.

GET /v2/questions/core.q14

{
  "question": {
    "code": "q14",
    "name": "Employment Status",
    "namespace_code": "core",
    "description": "What is your current working status?",
    "accessible": true,
    "message": "Question added in Q2 2009. Asked in all GWI Core markets.\n\nThe figures represent all internet users aged 16-64.\n\nRetired added as option in Q2 2015. Until Q4 2016, Self-employed and Freelancer were different options; from Q1 2017 onwards , Self-employed was modified to Self-employed / Freelancer and the Freelancer option was withdrawn.",
    "datapoints": [
      {
        "code": "8",
        "name": "Other",
        "accessible": true,
        "order": 7
      },
      {
        "code": "1",
        "name": "Full-time worker",
        "accessible": true,
        "order": 0
      },
      {
        "code": "2",
        "name": "Part-time worker",
        "accessible": true,
        "order": 1
      },
      {
        "code": "5",
        "name": "Full-time parent / stay-at-home parent",
        "accessible": true,
        "order": 3
      },
      ...
    ]
  }
}

From this response, we can see that question's namespace is core. The keen-eyed will also notice, it is exactly the parameter we sent to the question detail endpoint. This is unique question identifier. You can think of it as composed unique index: namespace_code.question_code (core.q14). Now that we know this question's namespace code (core), we can query for all available locations, waves and splitters for core namespace.

Waves

We can retrieve a list of available waves for our question core.q14 we queried above by simply using the namespace_code as a filter criterion to the waves filter endpoint.

POST /v2/waves/filter --data '{
  "namespaces": [
    {
      "code": "core"
    }
  ]
}'

{
  "waves": [
    {
      "id": "61",
      "name": "Q4 2021",
      "accessible": true,
      "code": "q4_2021",
      "date_start": "2021-10-01T00:00:00Z",
      "date_end": "2021-12-31T00:00:00Z",
      "kind": "quarter",
      "namespaces": [
          "core",
          ...
      ]
    },
    {
      "id": "62",
      "name": "Q1 2022",
      "accessible": true,
      "code": "q1_2022",
      "date_start": "2022-01-01T00:00:00Z",
      "date_end": "2022-03-31T00:00:00Z",
      "kind": "quarter",
      "namespaces": [
          "core",
          ...
      ]
    },
    ...
  ]
}

Locations

Constructing locations filter request is very easy. The only required filter criterion is namespace_code, but you can query for available locations in particular wave:

POST /v2/locations/filter --data '{
  "namespaces": [
    {
      "code": "core"
    }
  ],
  "waves": [
    {
      "code": "q1_2020"
    }
  ]
}'

{
  "locations": [
    {
      "id": "3",
      "iso_code": "arg",
      "name": "Argentina",
      "accessible": true,
      "code": "s2_54",
      "region": null,
      "namespaces": [
        {
          "code": "core",
          "wave_codes": [
            "q1_2020"
          ]
        }
      ]
    },
    {
      "id": "5",
      "iso_code": "aus",
      "name": "Australia",
      "accessible": true,
      "code": "s2_61",
      "region": null,
      "namespaces": [
        {
          "code": "core",
          "wave_codes": [
            "q1_2020"
          ]
        }
      ]
    },
    ...
  ]
}

Splitters

Getting available splitters is similarly very easy, just filter for splitters available for a question's namespace.

POST /v2/splitters/filter --data '{
  "splitters": [
    {
      "namespace_code":"core"
    }
  ]
}'

{
  "splitters": [
    {
      "code": "q2",
      "namespace_code": "core",
      "name": "Gender",
      "accessible": true,
      "segments": [
        {
          "code": "q2_1",
          "name": "Male",
          "accessible": true
        },
        {
          "code": "q2_2",
          "name": "Female",
          "accessible": true
        }
      ]
    },
    {
      "code": "q4",
      "namespace_code": "core",
      "name": "Age Groups",
      "accessible": true,
      "segments": [
        {
          "code": "q4_2",
          "name": "16 to 24",
          "accessible": true
        },
        {
          "code": "q4_3",
          "name": "25 to 34",
          "accessible": true
        },
        {
          "code": "q4_4",
          "name": "35 to 44",
          "accessible": true
        },
        {
          "code": "q4_5",
          "name": "45 to 54",
          "accessible": true
        },
        {
          "code": "q4_6",
          "name": "55 to 64",
          "accessible": true
        }
      ]
    },
    ...
  ]
}

Query with filters and splitter

To craft a query request filtered to respondents who responded in Q1 2020 wave in Australia, we pass the wave code (q1_2020) and location code (s2_61) to the request. We can also use splitter, in this case Gender (q2), but to enable the splitter functionality, we must provide also the individual segments of the splitter question - the individual gender datapoints. Which in this case are only Male (q2_1) and Female (q2_2).

POST /v2/query/stats --data '{
  "question": "q14",
  "audiences": [],
  "waves": [
      "q1_2020"
  ],
  "locations": [
      "s2_61"
  ],
  "datapoints": [
    "q14_1",
    "q14_2"
  ],
  "suffixes": [],
  "segmented_base": false,
  "splitter": "q2",
  "segments": [
      "q2_1",
      "q2_2"
  ]
}'

The response will be the asked question (q14) and all the asked datapoints (q14_1, q14_2), each filtered by the segments. In this case there are 4 different result groups for all of the possible combinations of q14_1, q14_2 and splitters q2_1, q2_2, in this case 4 different result groups.

{
  "meta": {
    "type": "DATAPOINTS-SEGMENTS",
    "question": "q14",
    "splitter": "q2"
  },
  "data": [
    {
      "datapoint": "q14_1",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 995,
        "positive_size": 3965330,
        "audience_sample": 1974,
        "audience_size": 7943238,
        "audience_percentage": 49.9,
        "audience_index": 123.6,
        "datapoint_sample": 1677,
        "datapoint_size": 6383296,
        "datapoint_percentage": 62.1
      },
      "segment": "q2_1"
    },
    {
      "datapoint": "q14_2",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 267,
        "positive_size": 1091705,
        "audience_sample": 1974,
        "audience_size": 7943238,
        "audience_percentage": 13.7,
        "audience_index": 73.1,
        "datapoint_sample": 784,
        "datapoint_size": 2968935,
        "datapoint_percentage": 36.8
      },
      "segment": "q2_1"
    },
    {
      "datapoint": "q14_1",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 682,
        "positive_size": 2417966,
        "audience_sample": 2175,
        "audience_size": 7857850,
        "audience_percentage": 30.8,
        "audience_index": 76.2,
        "datapoint_sample": 1677,
        "datapoint_size": 6383296,
        "datapoint_percentage": 37.9
      },
      "segment": "q2_2"
    },
    {
      "datapoint": "q14_2",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 517,
        "positive_size": 1877230,
        "audience_sample": 2175,
        "audience_size": 7857850,
        "audience_percentage": 23.9,
        "audience_index": 127.1,
        "datapoint_sample": 784,
        "datapoint_size": 2968935,
        "datapoint_percentage": 63.2
      },
      "segment": "q2_2"
    }
  ]
}

GWI Help Centre explains the terms: Primary datasets, Add-ons and Recontacts. Each primary dataset, add-on or recontact has its own namespace (note: the namespaces were introduced in the Question namespace section). Detailed information about a namespace can be obtained using namespaces filter endpoint:

POST /v2/namespaces/filter --data '{
  "namespaces": [
    {
      "code": "gwi-mys-lno"
    }
  ]
}'

{
  "data": [
    {
      "type":"namespaces",
      "id":"gwi-mys-lno",
      "attributes": {
          "code": "gwi-mys-lno",
          "name": "gwi-zeitgeist-june-2022",
          "parent_namespace_code": "gwi-ext",
          "type": "recontact"
      }
    }
  ]
}

where type can be:

• fresh for primary datasets and add-ons.
• recontact for recontacts.

In case a namespace is a recontact it uses a sample of respondents that has already answered the parent namespace survey. The parent namespace survey code is in the parent_namespace_code field.

Allowed Combinations of Questions from Different Namespaces

It is not possible to combine questions from any namespace with questions from any namespace in a single calculation query.

It is allowed to combine only questions from a recontact namespace with questions from its parent_namespace_code. This compatibility is for indefinite recontact parent relationship, i.e. recontact can be combined with its parent_namespace_code and with the parent_namespace_code of the parent_namespace_code, etc.

For example, assume the below namespaces:

• "code": "core", "type": "fresh", "parent_namespace_code":null
• "code": "gwi-r1", "type": "recontact", "parent_namespace_code": "core"
• "code": "gwi-r2", "type": "recontact", "parent_namespace_code": "gwi-r1"
• "code": "gwi-r3", "type": "recontact", "parent_namespace_code": "gwi-r2"
• "code": "gwi-r10", "type": "recontact", "parent_namespace_code": "core"

In the above example questions from namespaces core, gwi-r1, gwi-r2 and gwi-r3 can be freely combined in a single calculation query because there is a parent child relationship among all of them.

It is also possible to combine in a single calculation query questions from namespaces core and gwi-r10 because there is a parent child relationship between them.

However, it is not allowed to combine in a single calculation query questions from gwi-r10 with questions from namespaces gwi-r1 or gwi-r2 or gwi-r3 because there is not a parent child relationship between the gwi-r10 namespace and the other namespaces.

Supports the saving and retrieving of audiences.

Create Audience

Let's create a basic audience containing all Males in Age Group 16-24 years.

POST /v2/saved/audiences --data '{
  "name": "Male 16-24",
  "expression": {
    "and": [
      {
        "datapoints": [
          "q4_2"
        ],
        "min_count": 1,
        "question": "q4"
      },
      {
        "datapoints": [
          "q2_1"
        ],
        "min_count": 1,
        "question": "q2"
      }
    ]
  }
}'

The create audience endpoint will return the entire object that can be saved/cached to avoid extra GET calls. The meaning of all the fields can be found in create audience documentation.

{
  "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
  "v1_id": 10609642,
  "name": "Male 16-24",
  "created_at": "2022-06-13T08:23:38.202674Z",
  "expression": {
    "and": [
      {
        "datapoints": [
          "q4_2"
        ],
        "min_count": 1,
        "question": "q4"
      },
      {
        "datapoints": [
          "q2_1"
        ],
        "min_count": 1,
        "question": "q2"
      }
    ]
  },
  "updated_at": "2022-06-13T08:23:38.202674Z",
  "folder_id": null,
  "position": 0,
  "flags": [
    "authored"
  ],
  "user_id": 67087,
  "datasets": [
    "ds-core"
  ],
  "permissions": {
    "audience_overall": "accessible"
  }
}

List Audiences

We can now call list audiences endpoint to see our newly created audience.

GET /v2/saved/audiences

{
  "data": [
    {
      "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
      "v1_id": 10609642,
      "name": "Male 16-24",
      "created_at": "2022-06-13T08:23:38.202674Z",
      "expression": {
        "and": [
          {
            "datapoints": [
              "q4_2"
            ],
            "min_count": 1,
            "question": "q4"
          },
          {
            "datapoints": [
              "q2_1"
            ],
            "min_count": 1,
            "question": "q2"
          }
        ]
      },
      "updated_at": "2022-06-13T08:23:38.202674Z",
      "folder_id": null,
      "position": 0,
      "flags": [
        "authored"
      ],
      "user_id": 67087,
      "datasets": [
        "ds-core"
      ],
      "permissions": {
        "audience_overall": "accessible"
      }
    }
  ],
  "meta": {}
}

Get Audience by ID

Using get audience endpoint will result in the same exact response you would get from save audience response.

GET /v2/saved/audiences/886fccab-7c35-4133-aa1a-32cb2770268d

{
  "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
  "v1_id": 10609642,
  "name": "Male 16-24",
  "created_at": "2022-06-13T08:23:38.202674Z",
  "expression": {
    "and": [
      {
        "datapoints": [
          "q4_2"
        ],
        "min_count": 1,
        "question": "q4"
      },
      {
        "datapoints": [
          "q2_1"
        ],
        "min_count": 1,
        "question": "q2"
      }
    ]
  },
  "updated_at": "2022-06-13T08:23:38.202674Z",
  "folder_id": null,
  "position": 0,
  "flags": [
    "authored"
  ],
  "user_id": 67087,
  "datasets": [
    "ds-core"
  ],
  "permissions": {
    "audience_overall": "accessible"
  }
}

Update Audience

To only update some of the fields within the audience, like name or expression, you can use the update audience endpoint. This endpoint can be used to change a few fields without having to GET/PUT the entire audience.

There is also replace audience endpoint, which can be used to replace audience with whatever data is supplied in the PUT request, regardless of the previous state.

PATCH /v2/saved/audiences/886fccab-7c35-4133-aa1a-32cb2770268d --data
    '{
      "name": "Male 16-24 as",
      "expression": {
        "and": [
          {
            "datapoints": [
              "q4_2"
            ],
            "min_count": 1,
            "question": "q4"
          }
        ]
      }
    }'

{
  "data": {
    "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
    "v1_id": 10609642,
    "name": "Male 16-24 as",
    "expression": {
      "and": [
        {
          "datapoints": [
            "q4_2"
          ],
          "min_count": 1,
          "question": "q4"
        }
      ]
    },
    "folder": null,
    "curated": false,
    "category": null,
    "type": "user",
    "created_at": 1655107704,
    "updated_at": 1655110517,
    "user_id": 0
  }
}

Delete Audience

Deleting audience is straightforward. There is no response object, just HTTP 200 OK.

DELETE /v2/saved/audiences/886fccab-7c35-4133-aa1a-32cb2770268d

You can make sure audience was deleted by running:

GET /v2/saved/audiences/886fccab-7c35-4133-aa1a-32cb2770268d

{
  "error": "entity with v2ID 886fccab-7c35-4133-aa1a-32cb2770268d was not found in database",
  "error_type": "not_found",
  "code": 404
}

Audience Metrics for Stats Query

To use audience in a Query, you have to GET the Audience and fetch its id and expression attribute. Since we deleted the audience in the previous example, you can create a new one, or use any of your audiences.

Here is an example of the most basic Audience that can be used in a Query:

{
  "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
  "expression": {
    "and": [
      {
        "datapoints": [
          "q4_2"
        ],
        "min_count": 1,
        "question": "q4"
      }
    ]
  }
}

To run query with this audience applied, you simply add the audience object shown above to the query's audiences array:

POST /v2/query/stats --data '{
  "question": "q14",
  "audiences": [
    {
      "id": "886fccab-7c35-4133-aa1a-32cb2770268d",
      "expression": {
        "and": [
          {
            "datapoints": [
              "q4_2"
            ],
            "min_count": 1,
            "question": "q4"
          }
        ]
      }
    }
  ],
  "waves": [
      "q1_2020"
  ],
  "locations": [
      "s2_61"
  ],
  "datapoints": [
    "q14_1",
    "q14_2"
  ],
  "suffixes": [],
  "segmented_base": false,
  "segments": []
}'

Now the response data will contain metrics for each audience provided in the query for each datapoint queried. Metrics for such calculations are explained in GWI metrics explained.

{
  "meta": {
    "type": "DATAPOINTS-AUDIENCES",
    "question": "q14",
    "splitter": ""
  },
  "data": [
    {
      "datapoint": "q14_1",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 161,
        "positive_size": 695879,
        "audience_sample": 825,
        "audience_size": 3244330,
        "audience_percentage": 21.4,
        "audience_index": 53.1,
        "datapoint_sample": 1677,
        "datapoint_size": 6383296,
        "datapoint_percentage": 10.9
      },
      "audience": "886fccab-7c35-4133-aa1a-32cb2770268d"
    },
    {
      "datapoint": "q14_2",
      "waves": [
        "q1_2020"
      ],
      "metrics": {
        "positive_sample": 189,
        "positive_size": 718298,
        "audience_sample": 825,
        "audience_size": 3244330,
        "audience_percentage": 22.1,
        "audience_index": 117.8,
        "datapoint_sample": 784,
        "datapoint_size": 2968935,
        "datapoint_percentage": 24.2
      },
      "audience": "886fccab-7c35-4133-aa1a-32cb2770268d"
    }
  ]
}

Audience Metrics for Crosstab Query

Metrics can be queried on a single audience with an optional base audience. In the results, the audience size is "size", the number of responses is "sample". In addition, it's possible to query an intersection of a single audience with a base audience or intersection of two audiences with a base audience. For single audience fields "row" and "column" can be used interchangeably in the request body:

POST /v2/query/intersection --data '{
  "audiences": {
      "row": {
          "id": "8772f61d-e1da-4a07-af14-d3bc11d63a47",
          "expression": {
              "and": [
                  {
                      "question": "q2",
                      "datapoints": [
                          "q2_1"
                      ],
                      "min_count": 1,
                      "not": false
                  },
                  {
                      "question": "q4",
                      "datapoints": [
                          "q4_3"
                      ],
                      "min_count": 1,
                      "not": false
                  }
              ]
          }
      }
  },
  "locations": [],
  "waves": []
}'

Since this is the endpoint for an intersection and a single "row" audience is used, the "row" in the response contains the calculation results for the single audience. The following is the response with the metrics filled in:

{
  "meta": {
    "type": "INTERSECTION"
  },
  "data": {
    "audiences": {
      "column": {
        "audience": "0",
        "size": 1938474990,
        "sample": 4835761,
        "percentage": 100,
        "intersect_percentage": 100
      },
      "row": {
        "audience": "8772f61d-e1da-4a07-af14-d3bc11d63a47",
        "size": 300002849,
        "sample": 637371,
        "percentage": 15.5,
        "intersect_percentage": 15.5
      }
    },
    "base": {
      "size": 1938474990,
      "sample": 4835761
    },
    "intersect": {
      "size": 300002849,
      "sample": 637371,
      "percentage": 15.5,
      "index": 100
    }
  }
}

If your goal is to get metrics about the intersection of two overlapping audiences, you need to add both "row" and "column" fields. In fact, you can also add "base_audience" as a third audience. Both audiences "row" and "column" will also intersect with (base on) its "base_audience".

POST /v2/query/intersection --data '{
    "audiences": {
        "row": {
            "id": "5778296d-9df6-44f7-ab38-edac2376704d",
            "expression": {
                "or": [
                    {
                        "question": "q31818e",
                        "datapoints": [
                            "q31818e_107"
                        ],
                        "min_count": 1,
                        "not": false,
                        "suffixes": [
                            "4"
                        ]
                    }
                ]
            }
        },
        "column": {
            "id": "e80fef00-60ac-4942-9120-fbc4ab86ba4e",
            "expression": {
                "question": "q6",
                "datapoints": [
                    "q6_4"
                ],
                "min_count": 1,
                "not": false
            }
        }
    },
    "locations": [
        "s2_1",
        "s2_2",
        "s2_20",
        "s2_212",
        "s2_233",
        "s2_234",
        "s2_254",
        "s2_27",
        "s2_30",
        "s2_31",
        "s2_32",
        "s2_33",
        "s2_34",
        "s2_351",
        "s2_353",
        "s2_39",
        "s2_40",
        "s2_41",
        "s2_420",
        "s2_43",
        "s2_44",
        "s2_45",
        "s2_46",
        "s2_47",
        "s2_48",
        "s2_49",
        "s2_52",
        "s2_54",
        "s2_55",
        "s2_56",
        "s2_57",
        "s2_60",
        "s2_61",
        "s2_62",
        "s2_63",
        "s2_64",
        "s2_65",
        "s2_66",
        "s2_7",
        "s2_81",
        "s2_82",
        "s2_84",
        "s2_852",
        "s2_86",
        "s2_886",
        "s2_90",
        "s2_91",
        "s2_966",
        "s2_971",
        "s2_972"
    ],
    "waves": [
        "q1_2022",
        "q2_2022",
        "q3_2022",
        "q4_2021"
    ],
    "base_audience": {
        "id": "01741545-c7d3-421f-bb2b-c7fcfe48a5b9",
        "expression": {
            "and": [
                {
                    "question": "q5us",
                    "datapoints": [
                        "q5us_133"
                    ],
                    "min_count": 1,
                    "not": false
                }
            ]
        }
    }
}'

It will produce following response:

{
    "meta": {
        "type": "INTERSECTION",
    },
    "data": {
        "audiences": {
            "column": {
                "audience": "e80fef00-60ac-4942-9120-fbc4ab86ba4e",
                "size": 4486835,
                "sample": 1517,
                "percentage": 32.5,
                "intersect_percentage": 34.9
            },
            "row": {
                "audience": "5778296d-9df6-44f7-ab38-edac2376704d",
                "size": 2496127,
                "sample": 870,
                "percentage": 18.1,
                "intersect_percentage": 19.4
            }
        },
        "base": {
            "size": 13818224,
            "sample": 4745
        },
        "intersect": {
            "size": 870438,
            "sample": 294,
            "percentage": 6.3,
            "index": 107.4
        }
    }
}

Authorization in V2 API is same as in V1 API, i.e. authorization token is used. For more information refer to Authorization.

In addition, the V1 API current_user endpoint is replaced by token validation endpoint.

Work with Audiences in V2 API is similar to V1 API. However, there are several changes between V1 and V2 API:

• The V1 API shared attribute is discontinued.
• The V1 API created_at attribute is discontinued.
• The V1 API type attribute is discontinued.
• The V1 API curated attribute is discontinued. However, this information is present in the flags attribute in V2 API.
• The V1 API folder attribute is renamed to folder_id in V2 API.
• The V1 API options attribute in expression attribute is renamed to datapoints in V2 API.

Please, for more details on V2 API Audience endpoints refer to the Audiences chapter

The V1 Audience Folders endpoint is discontinued. In case you are missing this endpoint, please contact your account manager with the use case.

The way how questions are retrieved in V1 API is now discontinued. In V2 API questions must be retrieved in a step by step way by traversing Categories tree as described in section Basic Calculation Query.

In addition, list of datapoints and suffixes for an individual question is retrieved separately using one of the below endpoints:

• v2 Questions Filter
• v2 Question Detail

Note: the available_options attribute from V1 API was renamed to datapoints in V2 API.

The way how categories are retrieved in V1 API is now discontinued. In V2 API categories must be retrieved in a step by step way by traversing Categories tree as described in section Basic Calculation Query.

The legacy V1 API was designed at the time when GWI was offering only 1 syndicated study: GWI Core. Because of that V1 API Waves endpoint returns all waves that an API user has access to.

However, now GWI offers several syndicated studies and also custom studies. That's why the V2 API Waves endpoint is based on namespaces.

In general each namespace can have its own unique set of waves. That's why the V2 API Waves endpoint request contains a list of namespaces an API user wants to receive waves for. In case the list of namespaces in the request filter is empty, all combinations of namespaces and waves will be returned.

For detailed information refer to the v2 Waves Filter section.

The legacy V1 API was designed at the time when GWI was offering only 1 syndicated study: GWI Core. Because of that V1 API Locations endpoint returns all locations that an API user has access to.

However, now GWI offers several syndicated studies and also custom studies. That's why the V2 API Locations endpoint is based on namespaces and waves.

In general each namespace and wave couple can have its own unique set of locations. That's why the V2 API Locations endpoint request contains a list of namespace(s) and wave(s) an API user wants to receive locations for. Both the list of waves and list of namespaces are optional parameters. In case the list of waves is empty, all waves and locations combinations will be returned for the provided list of namespaces. In case both the list of namespaces and waves are empty, all combinations of namespaces, waves and locations will be returned.

For detailed information refer to the v2 Locations Filter section.

V1 API multipliers are renamed to splitters in V2 API.

The legacy V1 API was designed at the time when GWI was offering only 1 syndicated study: GWI Core. Because of that V1 API Multipliers endpoint returns all multipliers that an API user has access to.

However, now GWI offers several syndicated studies and also custom studies. That's why the V2 API Splitters endpoint is based on namespaces.

In general each namespace can have its own unique set of splitters. That's why the V2 API Splitters endpoint request contains a list of namespaces an API user wants to receive splitters for. In case the list of namespaces is empty, all combinations of namespaces and splitters will be returned.

For detailed information refer to the v2 Splitters Filter section.

The V1 Bookmarks endpoint is discontinued. In case you are missing this endpoint, please contact your account manager with the use case.

The V1 Saved Queries endpoint is discontinued. In case you are missing this endpoint, please contact your account manager with the use case.

V1 API Query is renamed to Stats Query in V2 API.

V1 API Query accepts id of a Saved Query. This feature is discontinued. V2 API Stats Query does not accept id of Saved Query.

Audiences in V1 API Query are represented by audience ID, however, audiences in V2 API Stats Query are represented by audience expression.

Some of the V1 API Query attributes are renamed or discontinued in V2 API Stats Query as described below:

• The filter.audiences attribute is base_audience attribute in V2 API Stats Query.
• The filter.locations attribute is locations attribute in V2 API Stats Query.
• The filter.waves attribute is waves attribute in V2 API Stats Query.
• The options attribute is datapoints attribute in V2 API Stats Query.
• The multiplier attribute is splitter attribute in V2 API Stats Query.
• The split_bases attribute is segmented_base attribute in V2 API Stats Query.
• The active_options attribute is discontinued.
• The metrics attribute is discontinued.

Some of the V1 API Query Response attributes are renamed or moved in V2 API Stats Query Response as described below:

• The data.by_audience, data.by_multiplier_segment and data.by_audience_and_multiplier_segment attributes are expressed as the value of the meta.type attribute in V2 API Stats Query Response. The meta.type attribute can have value: "DATAPOINTS", "DATAPOINTS-AUDIENCES", "DATAPOINTS-SEGMENTS" or "DATAPOINTS-SEGMENTS-AUDIENCES".
• All calculation results for V2 API are located in data array attribute in metrics attribute. In data array attribute the audience, datapoint, segment, suffixes and waves attributes specify the particular audience/datapoint/segment/suffixes/waves combination for the calculation results in the metrics attribute.
• The calculation results count attribute was renamed to positive_sample.
• The calculation results responses_count attribute was renamed to positive_sample.
• The calculation results horizontal_percentage attribute was renamed to datapoint_percentage.
• The calculation results percentage attribute was renamed to audience_percentage.
• The calculation results index attribute was renamed to audience_index.
• The calculation results weighted_universe_count attribute was renamed to positive_size.

For detailed information refer to the v2 Stats Query section.

Note: V2 API introduced the below calculation queries:

• Audience Wave Counts Query
• Crosstab Query

The V1 Fulltext endpoint is discontinued. In case you are missing this endpoint, please contact your account manager with the use case.