Audience and city
What is measured
- Audience: up to 3 customer types. Each one is a name and one sentence about who asks ("I am a university student with a small budget"). Every week the same prompts are asked as that customer, and you see the result next to your own measurement.
- City: up to 3 cities in the panel country. Every week the same prompts are asked from each city on Google AI Mode and AI Overviews. The panel needs at least one of these two engines.
By default the newest prompts are used (20 for audience, 15 for city). You can choose the prompts yourself.
Calls
| Call | Effect |
|---|---|
GET /panels/{panel_id}/audiences | Settings and the latest weekly comparison per customer type: report[].base_mentioned (your own measurement) and variant_mentioned (as that customer), cited rates, top competitors, history and every prompt with an excerpt |
PATCH /panels/{panel_id}/audiences | enabled, personas ([{id, name, text}], at most 3) and prompts (prompt ids, at most 20, or null for the newest). Fields you leave out keep their value. Keep id to keep a customer type's history; removing one deletes its history |
POST /panels/{panel_id}/audiences/suggest | Suggest customer types from your site and prompts. It does not save. At most 10 per panel per hour, shared with the panel |
GET /panels/{panel_id}/locations | Settings and the latest weekly comparison per city, same shape as audiences with city_id |
PATCH /panels/{panel_id}/locations | enabled, cities ([{id, name}], at most 3) and prompts (at most 15) |
GET /panels/{panel_id}/locations/cities?q=Porto | Check a city name in the panel country before saving. ambiguous: true means more than one city has that name: add the region, for example Portland, Oregon |
The first result arrives with the next weekly cycle (first_result: "next_weekly_cycle"). All writes accept dry_run: true.
Reasons
When a write is refused the answer is 422 validation_error with one of these reason values:
| Reason | Meaning |
|---|---|
aud_persona_short | A customer type needs a name and a sentence of at least 15 characters |
aud_persona_max | More than 3 customer types |
aud_persona_none | Turning audience measurement on needs at least one customer type |
aud_prompts_max, loc_prompts_max | Too many prompts chosen |
aud_prompts_none | None of the chosen prompts can be measured (inactive or brand questions) |
unknown_prompt | A prompt id does not belong to this panel |
loc_no_google | City measurement needs Google AI Mode or AI Overviews among the panel engines |
loc_not_found, loc_ambiguous | The city is not in the panel country, or more than one city has that name |
loc_max, loc_none | More than 3 cities, or none while turning it on |
MCP
get_audiences, update_audiences, suggest_audiences, get_locations, update_locations and find_city. Writes preview by default.