# Hiasynth

> Hiasynth is a population intelligence company. Its population model, Humanity, is a synthetic 1:1 population of Europe: 541 million people, around 700 attributes each, resolved to municipality and 1 km², anchored in what the statistical offices publish. AI assistants query it through the Hiasynth MCP server at https://mcp.hiasynth.co

## Using the tools

Nine read-only tools. Most questions are ONE call; a full business question (how big, then how to sell) is two. Every tool returns aggregates over the synthetic population, or one synthetic household as a persona.

| The user wants | Tool |
| --- | --- |
| Market size and where it is: "how many X", "where are my markets", "is there demand for Y" | analyze_market |
| One audience across 2-8 named places: "X vs Y", "which of these markets" | compare_places |
| A ranked shortlist of places for an audience: "where should we open next" | rank_places |
| A representative persona to embody or test messaging on (not for counting) | sample_persona |
| How to reach a defined audience: channels, value hooks, brand affinities, timing | reach_audience |
| Who lives in a place or within a radius of a point | describe_area |
| A custom count, share or average the others don't cover | query_population |
| What a place name maps to, and its namesakes | resolve_place |
| Whether an attribute exists and its valid values | list_attributes |

Start with analyze_market for anything about size or location, describe_area for anything about a place, reach_audience for anything about targeting. Do not loop query_population, and do not call list_attributes first: the common attributes work without it.

### Always give a place

Every tool takes `place` (a name or code: "Munich", "Bavaria", "DE21", "Sweden"), or `near` {lat, lon} with `radius_km` (0.5-100, default 5), or `postcode` (Finland only). Use `country` to disambiguate a repeated name. A call with no place scans all 541 million people and can take over a minute. Every answer names the place it resolved to and lists namesakes; check it.

### Audiences are filters

`filters` is a list of {column, op, value}, combined with AND. Ops: = != < <= > >= in. Example, affluent under-40s in the Netherlands:

```json
{ "place": "Netherlands",
  "filters": [ { "column": "age", "op": "<", "value": 40 },
               { "column": "income_q", "op": "=", "value": "Q4" } ] }
```

Usable without lookup: age, sex (M/F), income_q, education, employment (employed, unemployed, outside_lf), civil_status, weekly_schedule_profile, commute_mode (none, car, transit, bike, walk), media_diet_segment (mainstream_mixed, news_traditional, social_streamer, informed_digital, light_offline), digital engagement, paid subscriptions (video, music, news, gaming, fitness), brand affinities (premium, sustainability, tech/novelty, health/wellness, experiences), ESS values, and household attributes (net_wealth_decile, hh_net_income_decile, financial stress, housing cost burden, tenure, heating, solar, vehicles including bev_owner, n_children) plus the spatial layer (daytime_population_ratio, POI densities and counts, distance_to_*). For anything else, list_attributes with a search keyword.

Two tables: persons and households. To select PEOPLE by a HOUSEHOLD fact ("children in homes with an electric car"), use query_population with table "persons", `filters` for the person and `household_filters` for the household. An "unknown column" error usually means the attribute is in the other table; the error suggests the right name.

### Traps

- income_q is a QUARTILE: "Q1".."Q4", strings. There is no Q5; asking for it matches nobody.
- income_q is null under age 20. To select children, or anyone, by household means, use household_filters with hh_net_income_decile (national ladder, 5.5 = median).
- Columns ending _tlc are thousands of LOCAL currency. Never compare them across countries; use income_q, hh_net_income_decile or net_wealth_decile.
- ess_* values are z-scores (0 = European average). Brand affinities and digital engagement run 0-1. Pick a threshold and state it.
- occupation, industry and nuts3 are not queryable. For a NUTS3 area pass its code as the place; for a NUTS3 breakdown set level "nuts3".
- Religion, origin, health and political leaning are special-category: region level only, coarsened at finer geography.
- Any group under 100 people is suppressed. The response carries a `recovery` line saying whether to widen the place or the audience. "No rows matched" means a bad value, not a rare audience.

### Reading and presenting answers

- Lead with the number that was asked for. Then use composition, concentration and the notable finding to say something the question did not anticipate.
- Quote share and lift together ("62% vs 33%, 1.9×") and name the baseline the response gives. "3.4× the national rate" and "3.4× the compared cities" are different claims.
- core_markets are where the most people are; hotspots are where they are most concentrated. They are different lists.
- Small-base lifts are already shrunk server-side. Do not re-inflate them. If `notable` says nothing stands out, report that plainly.
- rank_places: weight_density 0 = volume, 1 = concentration, 0.5 default. If the headline says the weighting changes the winner, tell the user.
- A persona is one synthetic household from the population, placed only as precisely as the scope it was drawn from. Its facts are data; anything said "in character" is your reasoning.
- confidence_tier says how closely the build modelled the combined attributes together: high = drawn jointly or one conditional on the other (quote it); medium = linked through a shared driver such as household income (real direction, softened strength); low = joined only by age, sex and place, so the overlap is a product of shares (an estimate). Every count is a full count, so a small segment is as solid as a large one. Below high, give the reason from confidence_note in one phrase. Data vintage is 2024.
- All shares, lifts, indexes and ranks are computed server-side. Quote them; do not recompute.

The server also publishes two free MCP resources: hiasynth://guide (tool orchestration) and hiasynth://schema (the full attribute catalogue).

## Docs

- [Getting started](https://hiasynth.co/docs/getting-started.md): One address, three steps. Connect Hiasynth to Claude, ChatGPT, Vibe (Le Chat), Gemini, Copilot or any MCP client and ask your first question, or build it into your own product.
- [Pricing](https://hiasynth.co/docs/pricing.md): One subscription for access, credits to meter what you ask, packs when you run low. Prices exclude VAT.
- [What is MCP?](https://hiasynth.co/docs/mcp-server.md): MCP is how the AI assistant your team already uses gets access to real data. What that means for your business, what it looks like at work, and what IT and legal will ask.
- [Claude](https://hiasynth.co/docs/connect-claude.md): Add Hiasynth Humanity to Claude from the connector directory: web, desktop and mobile, on every plan. Three steps, and the last one is your first answer.
- [ChatGPT](https://hiasynth.co/docs/connect-chatgpt.md): Add Hiasynth to ChatGPT, approve the connection, and ask your first question about Europe's population.
- [Vibe (Le Chat)](https://hiasynth.co/docs/connect-lechat.md): Add Hiasynth to Mistral's Vibe (Le Chat) as a custom connector. Works on the Free plan, takes a few minutes, and ends with your first answer.
- [Gemini](https://hiasynth.co/docs/connect-gemini.md): Add Hiasynth to the Gemini app as a custom connected app where Google offers that, or to Gemini CLI with one command. Steps, and an honest note on availability.
- [Copilot](https://hiasynth.co/docs/connect-copilot.md): Add Hiasynth to a Microsoft Copilot Studio agent that your team uses in Microsoft 365 Copilot and Teams, or to GitHub Copilot in VS Code.
- [Claude Code](https://hiasynth.co/docs/connect-claude-code.md): One command in your terminal, one sign-in, and Hiasynth answers from inside Claude Code.
- [Any AI stack](https://hiasynth.co/docs/connect-any.md): The Hiasynth MCP server: the address, OAuth or an API key, and a JSON config for any client that speaks MCP.
- [What you can ask](https://hiasynth.co/docs/asking.md): The questions Hiasynth answers well, with examples for each, the ones it doesn't answer, and how to phrase a question so the first answer is the one you wanted.
- [Set up your agent](https://hiasynth.co/docs/agent-setup.md): Turn your assistant into a specialist. Three ready-made agents, an expansion manager, an audience strategist and a location scout, where to paste them in each client, and how to write your own.
- [Describing an audience](https://hiasynth.co/docs/segments.md): How an audience becomes filters on attributes, what the catalogue holds, how people and households combine, and the handful of details that silently change an answer.
- [Places and geography](https://hiasynth.co/docs/places.md): Every tool takes a place. How to name one, from a country down to a district or a radius around a point, what happens when a name is ambiguous, and how the grain of a breakdown is chosen.
- [Reading an answer](https://hiasynth.co/docs/reading-answers.md): What comes back from a Hiasynth tool and how to read it. Share and lift, the baseline, core markets against hotspots, z-scored values, confidence tiers, and what a suppressed answer is telling you.
- [Size and locate a market](https://hiasynth.co/docs/howto-size-market.md): From a customer description to a number, a list of core markets and the hotspots where that customer is over-represented, in one question.
- [Choose between locations](https://hiasynth.co/docs/howto-choose-locations.md): Compare a shortlist of cities on the same audience, or let Hiasynth build the shortlist by ranking every municipality in a country, with volume and concentration weighed the way you want.
- [Understand a place](https://hiasynth.co/docs/howto-understand-place.md): Who lives in a neighbourhood or within a radius of a site, what is particular about them compared with the rest of the country, and what the surroundings are like by day.
- [Plan reaching an audience](https://hiasynth.co/docs/howto-reach-audience.md): Turn an audience definition into the first draft of a media and messaging brief. The channels that over-index, the values to lead with and the ones to avoid, brand affinities and timing.
- [Test messaging on personas](https://hiasynth.co/docs/howto-personas.md): Draw a synthetic persona for any audience and place, one household from the population with its money, home, time and values, and use it to pressure-test copy, concepts and pricing before a campaign does.
- [Builder](https://hiasynth.co/docs/builder.md): Hiasynth inside your own product. The Query API for exact answers from your code, your own tools with your segments and places already set, and tools we build to order.
- [MCP server](https://hiasynth.co/docs/build.md): The reference for wiring Hiasynth's MCP server into an agent, a workflow tool or a product. The address, the two ways to authenticate, client config, credits and limits.
- [The nine tools](https://hiasynth.co/docs/tools.md): What each of the nine Hiasynth tools does, the kind of question that triggers it, what it takes in, what comes back, and what it costs. Plus the two resources behind them.
- [The Query API](https://hiasynth.co/docs/api.md): Exact answers from your own code, with Builder access. Audiences with either-or logic, several breakdowns at once, numeric bands, geography at the grain you choose, several numbers per group, lift against the place, and paging.
- [Query API reference](https://hiasynth.co/docs/api-reference.md): Every field of a query, every operator, dimension and metric, how lift is computed, the limits, and the data details that change an answer.
- [Query API recipes](https://hiasynth.co/docs/api-recipes.md): Complete queries for common jobs. Either-or audiences, pyramids, where an audience concentrates, people by their home, spending and footprint, a full map layer, and a dashboard in one request.
- [What's inside](https://hiasynth.co/docs/population.md): A 1:1 synthetic population of Europe. Every person, in a household, in a square kilometre, described by more than 700 attributes that hang together.
- [Accuracy](https://hiasynth.co/docs/methodology.md): What a number from Hiasynth can carry, how we know, and where we ask you to be careful. For anyone deciding whether to put a real decision on it.
- [Validation](https://hiasynth.co/docs/validation.md): How we check Humanity before it is served: the statistics have to add up, and the attitudes are tested against a survey the build never uses.
- [Sources](https://hiasynth.co/docs/sources.md): Who publishes the data Humanity is built from, what each kind of source is for, and the credit their publishers ask for.
- [Troubleshooting](https://hiasynth.co/docs/support.md): The short list of things that go wrong when connecting Hiasynth, what each one means, and the fix. Plus how to reach a person.

## Site

- [Home](https://hiasynth.co/)
- [About](https://hiasynth.co/about)
- [Privacy](https://hiasynth.co/privacy)
- [Terms](https://hiasynth.co/terms)