The nine tools

You never pick a tool yourself. You ask, and your assistant picks. This page is for when you want to know what it has to choose from: what each tool is for, what it needs from you, and what it hands back. Every tool is read-only, and every one takes a place.

At a glance

Most questions are one call. A full business question, how big is it and how do I sell to it, is two: analyze_market and then reach_audience on the same audience.

analyze_market

The question. How many people match, and where are they. "Is there a market for premium e-bikes in the Netherlands?"

Takes. An audience and a place. Optionally the grain of the breakdown and how many places to list.

Returns. The size, what sets the audience apart, the core markets, the hotspots and, inside a city, the 1 km² cells where it clusters. Start here for anything about size or location: it is a complete answer in one call. Walkthrough: Size and locate a market.

compare_places

The question. The same audience, in places you name. "Munich, Hamburg or Vienna for a music app aimed at 25 to 39 year olds?"

Takes. Two to eight place names or codes, and an audience.

Returns. For each place, what the name resolved to, the count, the share, an index and a rank by size and by density. The baseline is the places you named, pooled, and not Europe. Walkthrough: Choose between locations.

rank_places

The question. The best places for an audience, when you don't have a list yet. "Where in Sweden should we open next?"

Takes. An audience, an area to search in, a grain for the candidates, how many to return, and one dial: weight_density, from 0 for sheer numbers to 1 for concentration. The default is 0.5.

Returns. A ranked shortlist with the reach, local share, density and fit of each place, the formula it used, and a warning when a different weighting would have changed the winner. Walkthrough: Choose between locations.

sample_persona

The question. A representative person to write for, role-play, or test messaging against. "Give me two contrasting personas for affluent thirty-somethings in Bavaria."

Takes. An audience, optionally a place, and whether the second persona should be similar to the first or a complement to it.

Returns. Two composite archetypes, each with a size, a profile, values, media and the regions where it is most common. Given a place, each also comes with its household's lifestyle: the spending categories that over- and under-index against the national average, the diet mix, and the carbon footprint. Never a record of one person, and not the tool for "how many". Walkthrough: Test messaging on personas.

reach_audience

The question. How to reach and talk to an audience you have already defined. "How do I reach sustainability-minded thirty-somethings in Germany?"

Takes. An audience and a place, anything from a country down to one neighbourhood.

Returns. Paid video, music, news, gaming and fitness subscriptions with rate and lift, the dominant media diet, the values to lead with and the ones to avoid, brand affinities, and timing. Walkthrough: Plan reaching an audience.

describe_area

The question. Who lives in a place. "Who lives within three kilometres of this address?" "Describe Södermalm."

Takes. Only a place: a name, a code, or a point with a radius.

Returns. Demographics, households, economics, distinctive values and media profile, each against the rest of the country, and a lifestyle block: what households there spend more and less of their budget on than the national average, what they eat, and their carbon footprint split into car, heating, flying and food. It is the cheapest composite tool, and the natural first step for siting, planning and development. Walkthrough: Understand a place.

query_population

The question. Anything specific the tools above don't cover: one count, one share, one average, grouped the way you want it. "How many children aged 3 to 10 in Germany live in a household with an electric car?"

What it takes. A table (persons or households), filters, an optional group-by, a metric (count, share or avg of a column) and a place. Household attributes can go straight into filters, where they select people by the household they live in. That is how a question crosses the two tables: the children are persons, the electric car belongs to the household. The older household_filters list does the same and still works.

What comes back. The number, or a grouped table of at most 200 rows. No composition and no narrative. It is the escape hatch for people building their own chains of calls, and the composite tools are nearly always a better first move.

resolve_place

The question. What a place name maps to. Your assistant uses it when a name is ambiguous or an answer came back for an unexpected area.

What comes back. The matched place, its level (country, region, municipality, district), its code and population, and any other places with the same name. There are four Södermalms in Sweden; this is how you find out you got the one in Stockholm. Places and geography has the detail.

list_attributes

The question. Whether an attribute exists and what it is called. "Is there something for solar panels?" "What can I filter on for electric vehicles?"

What comes back. With no arguments, a table of contents: the attribute groups and how many columns each holds. With a keyword, the matching columns with their meaning, table and valid values. It is free, and the common attributes work without it, so your assistant should only need it for the unusual ones. Describing an audience covers what is in the catalogue.

What every tool has in common

• A place. A name, a code, a postcode or a point with a radius. Naming one is what makes an answer fast. See Places and geography.
• An audience as filters. The same filter shape works on every tool that takes an audience. See Describing an audience.
• Aggregates only. Counts, shares, distributions, lifts, composites. No tool returns a person.
• A headline first. Every answer leads with one sentence your assistant can use directly, followed by the numbers behind it.
• Computed numbers. Shares, lifts, indexes and ranks are calculated on our side. Your assistant quotes them; it does not do the arithmetic.
• A confidence tier and a vintage. See Reading an answer.
• A privacy floor. Anything under 100 people is never shown. The answer tells you what to widen instead.

Two resources

Besides the tools, the server publishes two documents your assistant can fetch when it needs them. Neither costs credits.

• hiasynth://guide teaches the assistant which tool fits which question, how to define an audience, and how to read what comes back.
• hiasynth://schema is the full attribute catalogue with meanings, valid values and the provenance of each column.

For builders

Connection details, authentication and credit handling are in Build with Hiasynth. The tool names and inputs on this page are the API: what you see here is what tools/list returns.