Place content in markets and areas

A campaign for teenagers in Oslo and a price list for the Nordic countries are each written for a place. kapi records the place as a point on a geo axis. A rule kept for a place holds at every place inside it, so a rule kept for Norway applies to the Oslo campaign.

This guide uses the KapiMart sample. Kapi Desktop opens it with Try the sample. Run the commands in the sample's folder.

Look a place up

A geo axis takes place ids. The built-in places are the world, the UN regions, every country and every country's subdivisions (counties, states, provinces). The id of a country or a subdivision is its ISO code in lower case. Look a place up by name or id:

kapi context places oslo

oslo          Oslo          locality     world › europe › northern-europe › no › no-03 › oslo
no-03         Oslo          subdivision  world › europe › northern-europe › no › no-03
greater-oslo  Greater Oslo  metro        world › europe › northern-europe › no › greater-oslo

Each line shows the id, the name, the type and the path from the world down. no is Norway and no-03 is the county of Oslo. The other two places are declared in the sample's recipe. --within <id> lists the places directly below one place. --json prints the result as JSON.

Declare your own places

A city, a neighbourhood or a sales territory is a place you declare under places: in kapi.yaml. Each place either sits within places or is made of places:

kapi.yaml

places:
  nordics:
    name: Nordics
    of: [no, se, dk, fi, is]
  oslo:
    name: Oslo
    type: locality
    within: no-03
    centroid: [59.91, 10.75]
    refs: [wikidata:Q585, geonames:3143244]
  grunerlokka:
    name: Grünerløkka
    type: neighbourhood
    within: oslo
  greater-oslo:
    name: Greater Oslo
    type: metro
    of: [no-03, no-32]

Oslo sits within the county no-03, so a rule that holds in Norway also holds in Oslo. The Nordics are made of five countries, so a rule for the Nordics holds in each of them. Greater Oslo is made of two counties, so content at Oslo or Grünerløkka sits inside it.

Containment comes from the within and of declarations alone. The map uses a centroid or a shape file only to draw a place.

type names the kind of place (locality, district, neighbourhood, metro, territory and others). A place declared with of and no type is a territory. refs records the place's ids in Wikidata, GeoNames and similar gazetteers. The project file reference lists every key.

Make the market a geo axis

Name the axis under axes: and give it kind: geo. Its values are then place ids, and kapi checks each value when it loads the recipe:

kapi.yaml

axes:
  market:
    kind: geo
    label: Market
  age:
    kind: range
    label: Reader age
    unit: years

Put content at a place

A collection sits at a market the way it sits at a brand. The sample's Oslo youth campaign is for readers aged 13 to 17 in Oslo. Its pick-up page is about one neighbourhood, so that item sits at Grünerløkka:

kapi.yaml

collections:
  - name: Oslo youth campaign
    base: campaigns/oslo
    channel: kapimart/marketing
    coordinates:
      market: oslo
      age: 13-17
    content:
      - path: "en/grunerlokka.md"
        target: "{lang}"
        coordinates:
          market: grunerlokka
      - path: "en/*.md"
        target: "{lang}"

If a value is not a place id, the recipe fails to load and the error suggests the correct id:

Error: invalid project file /srv/site/kapi.yaml: collections[4]: collection "Oslo youth campaign": coordinates.market: axis market: "Oslo" is not a place. Write it in lower case: oslo

With no arguments, kapi context places lists the places your recipe declares:

kapi context places

greater-oslo  Greater Oslo  metro          world › europe › northern-europe › no › greater-oslo
grunerlokka   Grünerløkka   neighbourhood  world › europe › northern-europe › no › no-03 › oslo › grunerlokka
nordics       Nordics       territory      world › europe › northern-europe › nordics
oslo          Oslo          locality       world › europe › northern-europe › no › no-03 › oslo

Keep a rule for Norway

In Norway the address form asks for the county. In other markets it asks for a state or province. Record a note from the store's strings and place it in Norway:

kapi context note --term County --instead-of "State / Province" \
  --seen-in src/en/checkout-flow.json --point market=no

#0q9cg2vjqx  2026-10-17T11:32:41Z  person  observe  term "County", not "State / Province"  [suggested]

A note holds where its evidence was seen. Here that is the store's strings, on the kapimart/store channel. --point market=no narrows the note from the store's market: world to Norway. The Oslo campaign is on the kapimart/marketing channel, so the note does not yet apply to its pages. Keep the note and widen it beyond the channel where it was seen:

kapi context review --keep 0q9cg2vjqx --widen-to channel

#0q9cg9507h  2026-10-17T11:32:48Z  person  keep  of #0q9cg2vjqx
  written to the project's terms store

Your ids will differ. kapi context review lists the open suggestions and their ids.

Check the rule at the Oslo content

Print what applies to the campaign's page:

kapi context campaigns/oslo/en/summer-pass.md

Say this, not that:
...
- County, not "State / Province" [en]
...

The rule was kept for Norway and the page sits at Oslo, which sits within Norway, so the rule holds there. It also holds at the Grünerløkka page. The store's strings sit at market: world, which is wider than Norway, so the rule does not apply to them. kapi context prints the exclusion:

kapi context src/en/checkout-flow.json

Keep as it is in this file:
- "State / Province" is correct here; do not rename it to "County". That rename holds only in campaigns/oslo/en/.

See it on the map

Open the sample in Kapi Desktop, choose Explore in the Context hub, and open Map. The map opens on the narrowest region, country or place made of countries that contains every place the recipe declares and every place its content sits at. For the sample, that is the Nordics. A note kept for a market outside it, such as Japan, appears when you select World in the path above the map. When the market is filtered, the map opens on the selected records instead. Click a place to drill down:

1. Click Norway to show its counties. The county of Oslo is filled because records sit there. The other counties are hatched where a rule kept for Norway or the Nordics holds.
2. Click Oslo to show the places the recipe declares inside it. Oslo is drawn as a circle at its centroid. A declared place with a shape: file is drawn as its outline. A place with neither is listed beside the map.
3. Hover Greater Oslo beside the map to outline the two counties it is made of. Click a place to keep only the records that hold there.

Grid draws one tile of equal size per country, so a large country takes the same area as a small one. Explore your context covers the rest of the view.

Next steps

• Project file reference: every key of places:, and the errors a recipe load reports.
• kapi context places: the command and its flags.
• Growing context: notes, review, and widening a rule.
• Context: the axes a project declares.