# How GroundTruthData works

> A plain-English overview of where the numbers come from and how your AI assistant gets cited answers.

GroundTruthData answers questions about **places in South Africa** (crime, population and
rainfall for police stations, wards, municipalities and provinces) inside the AI assistant you
already use. Every number comes with its source.

## What you do

1. Connect GroundTruthData to your assistant once (see the [Quickstart](/docs/quickstart)).
2. Ask a normal question, for example: *"How did murders change in Khayelitsha last year?"*
3. Your assistant looks up the figures with our tools and answers with a citation, in this shape
   (the figures below are placeholders, not real numbers; see the [Tool reference](/docs/tools)
   for real responses):

> SAPS recorded **N murders** at *a named police station* in *a financial year*.
> *Source: South African Police Service, Crime Statistics.* Note: these are crimes recorded by
> police, not all crime. Figures cover the police station's area.

## Where the numbers come from

1. **Public sources only.** We use published, publicly available data: SAPS crime statistics,
   Municipal Demarcation Board ward and municipal boundaries, WorldPop population estimates,
   CHIRPS satellite rainfall and OpenStreetMap facility counts. We never get around logins, and we collect politely. See
   [Coverage](/coverage) for each source and its licence.
2. **No personal information.** We keep only approved fields. Names, ID numbers and contact
   details are dropped before anything is stored.
3. **Lined up on one map.** Each source uses its own map (police station areas, wards, satellite
   grids). We line them up so figures can be given per ward, municipality or province. Crime
   stays at police station and province level, because police areas do not match wards.
4. **Defined metrics.** Every figure we serve has a name, a clear definition and its caveats.
   Your assistant can ask what is available at any time.

## What you get back

Every answer includes:

- **Citations**: the source, publisher, licence, the date we retrieved it and the data version.
- **Caveats**: for example, that a population figure is a modelled estimate, not a census.
- **Summaries, not downloads**: totals, averages and comparisons, with limits on size. We do not
  offer bulk exports of the underlying data.

See [Citations and provenance](/docs/citations) and [Tools](/docs/tools) for the details.

## Signing in, keys and plans

- **Connectors** (Claude, ChatGPT) send you to groundtruthdata.co.za to sign in and approve
  access. See [Authentication](/docs/authentication). Connector sign-in is coming at launch;
  until then, use an API key.
- **API keys** are for scripts and agents. Create them in your dashboard. A key is shown once;
  we store only a scrambled fingerprint of it.
- **Plans** are flat monthly subscriptions with clear daily and monthly limits. No credits and no
  surprise overage charges. When you reach a limit, the tool says so and tells you when it
  resets. See [Plans and limits](/docs/limits).

> **Evidence, not advice**
>
> GroundTruthData gives you sourced figures to support your own judgement. It is not legal,
> financial or safety advice.