Skip to main content
The Spark API is designed to provide precise insights by combining audience definitions with specific questions. For example, “How do young parents discover brands?”. Structuring your query correctly ensures that the API returns the most relevant and actionable data. How to construct a query…
  1. Audience Definition: Clearly define the audience you want insights about. This can include demographics, interests, behaviors, or other characteristics. You can define one or more audiences in your query.
    • Example: “Eco-conscious millennials in the UK.”
    • Example: “Tech-savvy Gen Z globally.”
    Alternatively, if your organization has already created and shared audiences internally via GWI platform, you can define those known audiences by specifying their ids under the docked_audiences field. Using these predefined audiences will ensure that any returned insights are based on these specific audiences. You can find the list of audiences using /v2/saved/audiences.
  2. Specific Question: Ask a targeted question related to your audience. The question should be clear and concise to help the API retrieve the right data points.
    • Example: “What are their favorite social media platforms?”
    • Example: “Which topics are they most interested in?”
  3. (Optional) Define a Time period:
    • Clearly define what time period you are interested in i.e. q1 2024, If no time period is specified, the API will automatically use data from the last four waves (typically the previous year).
    • The selected timeframe will be echoed in the response, so you know which periods the insights are based on.
  4. (Optional) Select specific dataset(s):
    • The chat runs against the default dataset that is available to the user.
    • To query a different root dataset, pass a single dataset_code (for example ds-usa).
    • To query a root dataset together with one or more of its add-on studies, pass dataset_codes with values that all belong to the same dataset tree (a root and its children, for example ["ds-core", "ds-work"]).
    • You can discover the dataset codes available to your subscription via /v1/spark-api/datasets.
    • When both fields are provided, dataset_codes takes precedence and dataset_code is ignored.
    Request