> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/access/account-creation-and-onboarding-guide/geography.md).

# Geography

## Overview

Geography tells the system which places your organisation serves and how they fit inside each other. Complaints are linked to these places, so the right staff can see and handle them.

Your geography is made of levels, arranged from biggest to smallest. This order is called a hierarchy. Each place inside it is called an area. For example:

<table><thead><tr><th width="256.6015625">Level</th><th>Example areas</th></tr></thead><tbody><tr><td>County (top level)</td><td>Bomet County</td></tr><tr><td>Sub-county</td><td>Bomet East, Bomet Central, Chepalungu</td></tr><tr><td>Ward (lowest level)</td><td>Silibwet Township, Chesoen, Merigi</td></tr></tbody></table>

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2Fvnqvkbz34bTJBFEHv0yd%2Funknown.png?alt=media&amp;token=96d3882d-04ce-4e64-aed8-c61d26471e75" alt="" height="297" width="624"></div>

{% hint style="info" %}
**Important:** Plan your levels before you start. Once a hierarchy is created and onboarding is completed, its name and levels cannot be changed or deleted.

Areas cannot be deleted, renamed or moved once they are added. You can only add new ones. You need at least two levels to continue.
{% endhint %}

## Steps

### Choose how to add your places

The Geography page asks "How do you want to bring in your geography?" and offers three options:

<table><thead><tr><th width="138.796875">Option</th><th>Best for</th></tr></thead><tbody><tr><td>Preconfigured boundaries</td><td><p>The quickest choice. Uses the list of places already held for your country, if available. </p><p>This is a copy of the geographic boundary dataset obtained from sources such as OCHA COD-AB and geoBoundaries.</p><p>Select: Use these boundaries.</p></td></tr><tr><td>Fetch boundaries</td><td><p>Searching for your county or region in official public map sources and bringing in its places, including their map shapes. </p><p>Select Search boundaries.</p></td></tr><tr><td>Upload from Excel</td><td><p>Using your own list. Best when you need exact local names or areas missing from the other sources. </p><p>Select Upload a file.</p></td></tr></tbody></table>

{% hint style="info" %}
**Tip:** If some areas of importance to you are not present in the preconfigured or fetched list, use Upload from Excel.
{% endhint %}

### Option A: Preconfigured boundaries

Concepts for pre-configured boundaries

Boundaries loaded as Pre-configured have been validated against a copy of a map from a different source. If both sources of data drew an area in nearly the same place, you can trust it more. This check is what the screens call Confidence - Confirmed and Partly confirmed.

During the flow to load pre-configured boundaries, you may come across the following:

<table><thead><tr><th width="264.14453125">What you see</th><th>What it means</th></tr></thead><tbody><tr><td>Official boundaries for Kenya + High confidence</td><td>The map you're using for your country and its overall confidence rating.</td></tr><tr><td>OCHA COD-AB · Oct 2019</td><td>The data source used for the map and the year the boundaries were released. </td></tr><tr><td>A sentence such as "Counties confirmed. Sub-counties come from one source only."</td><td>A one-line summary of which layers were checked and which weren't.<br><br>This is seen when a certain level of boundary hierarchy could not be validated with an alternate data source. </td></tr><tr><td>"Confirmed means a second, independently drawn set has nearly the same areas…"</td><td>A reminder that "confirmed" means two maps agree. It doesn't mean your government has approved this file, and "one source only" means a layer couldn't be checked, not that it's wrong.</td></tr><tr><td>"The agreement check failed when this boundary data was built…"</td><td>We were not able to validate the boundary data to sufficient satisfaction and so there's no rating assigned.<br><br>You can still use the map or choose to use the “upload from excel” option for more robust boundaries.</td></tr><tr><td>"This server's boundary data predates the agreement check…"</td><td>The map data was loaded before the checking feature existed, so there's no rating. You can still use the map.</td></tr></tbody></table>

Boundary confidence and validation badges:

<table><thead><tr><th width="181.72265625">Badge</th><th width="265.02734375">Meaning</th><th>Action to be taken</th></tr></thead><tbody><tr><td>✅ Confirmed</td><td>At least 9 in 10 areas in this layer appear in nearly the same place on the second map.</td><td>None. This is the best result.</td></tr><tr><td>◌ Partly confirmed · 83%</td><td>Between half and 9 in 10 of the areas match. The number is the share that matched.</td><td>Review the names and boundaries and check if there are administrative boundaries you require, but are not present in the pre-configured data.</td></tr><tr><td>◌ Differs · 40%</td><td>Fewer than half match. The two maps disagree a lot. This often happens when areas were redrawn, for example new wards.</td><td>Review the area names and boundaries carefully. If they're out of date, use Upload from Excel.</td></tr><tr><td>⊘ One source only</td><td>The second validation map doesn't have this layer at all, so it couldn't be checked. That doesn't mean it's wrong.</td><td>Review these boundaries thoroughly.</td></tr></tbody></table>

#### Common Messages Observed:

<table><thead><tr><th width="321.47265625">Message</th><th>What to do</th></tr></thead><tbody><tr><td>Select at least two levels to form a hierarchy.</td><td>Tick another layer.</td></tr><tr><td>Selected levels must be contiguous… Re-include Level 2…</td><td>You skipped a layer in the middle. Tick it again, or untick from the top or bottom instead (Evaluate your requirement).</td></tr><tr><td>Name every selected level (missing: Level 3).</td><td>Fill in the name for that layer.</td></tr><tr><td>A "…" hierarchy already exists… with levels [County → Ward], which do not match your mapped levels…</td><td>Your workspace already has areas set up with different layer names. Rename your layers to match exactly, or add the areas through Upload from Excel → Use an existing hierarchy.</td></tr></tbody></table>

1. Select Use these boundaries (Preconfigured) - If your base country of operations has pre-tested and loaded maps, you may use this. If not present, kindly raise a request with the eGov Foundation.&#x20;

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FVLa74sKPzhrr8CONM7Me%2Funknown.png?alt=media&amp;token=90022b8a-a2e5-4fd4-8a81-36429b275920" alt="" height="391" width="624"></div>

2. From the country’s boundaries, select the area you want to select for your map. For example, for the Country Mozambique, if your Complaint Management System is only for the city of Cidade de Maputo, search for that area in the search bar.&#x20;

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FQLxzpwnf5iSzT6wSUxBj%2Funknown.png?alt=media&amp;token=ef8189db-cdaa-444b-95ce-4f04bc2111e9" alt="" height="391" width="624"></div>

3. You will see the levels of the hierarchy of geography that were found. Select the levels you want to include. They must be continuous; that is, you cannot skip a level in the middle. Example: In a hierarchy containing Country → County → Sub-county, you cannot only select Country and Sub-county.\
   \
   You will be able to review the geographic boundaries in map view on this page as well.&#x20;

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2F6qYDOL0cHk8Xliq8SWBK%2Funknown.png?alt=media&amp;token=10c4b119-ff41-4d0f-b305-f43623e365dc" alt="" height="391" width="624"></div>

4. Give each level a name. Example: County, Sub-county, Ward. The system suggests names where it can.

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FVzuEyCYw2pzEuI8LFhu9%2Funknown.png?alt=media&amp;token=2b8dfde3-05d0-446f-9f7f-e6791f3b1314" alt="" height="391" width="624"></div>

5. Once completed, select Create Hierarchy & Boundaries. This takes you to a page confirming the creation of geographic boundaries.

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FkQxxGIV2HzH48RC637cV%2Funknown.png?alt=media&amp;token=77d6171f-1f52-4c85-af09-c637a1591481" alt="" height="391" width="624"></div>

6. Click on “Back to Geography” to move to the main Geography page. Here you have the option to edit and delete the newly created boundaries if required.&#x20;

### Option B: Fetch open-source boundaries

With this option, you search for your city, county or region by name. The system then brings in that place and every smaller area inside it, along with the map shape of each area. You decide which levels to keep, give each level a name, and the system creates your hierarchy and areas for you.

#### When to use this option

<table><thead><tr><th width="355.640625">Use Fetch boundaries when</th><th>Use another option when</th></tr></thead><tbody><tr><td>Your country has no preconfigured boundaries, or the card says they are unavailable.</td><td>Preconfigured boundaries are available for your country and cover the areas you need (Option A).</td></tr><tr><td>You want the boundaries from a particular public map source.</td><td>You need exact local names, or areas that public maps don't have (Option C: Upload from Excel).</td></tr><tr><td>You want the real map shapes of your areas without preparing any files.</td><td>Your areas were recently redrawn and the public maps are out of date (Option C).</td></tr></tbody></table>

#### Boundary source

The boundary source is where the map data comes from. All of them are free, public datasets. Your administrator decides which sources appear in the list, so you may see only some of these.

<table><thead><tr><th width="263.96875">Source shown on screen</th><th>What it is</th></tr></thead><tbody><tr><td>Official — best of COD-AB / geoBoundaries per country</td><td>Government-derived boundaries. For each country, the system picks whichever of the two official sets goes down to the smallest areas.</td></tr><tr><td>OCHA COD-AB</td><td>Boundaries published by the United Nations (OCHA) for humanitarian work.</td></tr><tr><td>geoBoundaries</td><td>An open, research-based collection of government boundaries.</td></tr><tr><td>Overture Maps (OpenStreetMap-derived)</td><td>Open map data built from OpenStreetMap, which is drawn by volunteers worldwide.</td></tr><tr><td>Geoapify (hosted)</td><td>An online service that also uses OpenStreetMap data.</td></tr></tbody></table>

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FrPoysOwWUYDn7eL8w4no%2Funknown.png?alt=media&amp;token=238db405-f135-45dc-a9b2-96bbd9c8bfe7" alt="" height="391" width="624"></div>

You can select a Boundary source as required.&#x20;

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FjYZHQZAgze1NtudD1m5R%2Funknown.png?alt=media&amp;token=7fed0286-335c-4b8a-8270-e3f66798909f" alt="" height="391" width="624"></div>

Once the source of boundary data and the highest-level area are selected, the steps are similar to those of “Pre-configured boundaries”.

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FZCg0HiwXSdqmcJPp4ynN%2Funknown.png?alt=media&amp;token=a4df54c8-60a9-422b-8b37-37b28abc1ba5" alt="" height="391" width="624"></div>

### Option C: Upload from Excel

#### 1. Set up your levels

1. Select Upload a file.
2. If you already have a hierarchy, choose Use an existing hierarchy to add more areas, or Create a new hierarchy.
3. For a new one, enter a Hierarchy Type Name. “ADMIN” is the auto-filled value, but you can change that to align with your requirements. You cannot use the name ‘WORKSPACE’.
4. Under Define Levels (top to bottom), type your levels. Example: County, Sub-county, Ward. Use Add Level for more, or the X to remove one.
5. Select Create Hierarchy.

<div align="left"><img src="https://2002286464-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FK894BCuKVRy7QDBs06em%2Fuploads%2FKq7S9RSq1azQj0dPdyaG%2Funknown.png?alt=media&amp;token=8bf50082-8ca7-4944-9827-1759a2f379bb" alt="" height="391" width="624"></div>

#### 2. Fill in the spreadsheet

1. Select Download Template. It already has one example row for each level.
2. Replace the examples with your own areas, one row per area. Keep the column headings as they are.

<table><thead><tr><th width="144.72265625">Column</th><th width="424.74609375">What to type</th><th>Required?</th></tr></thead><tbody><tr><td>code</td><td>A short unique code for the area, for example MAPUTO_CTRL.</td><td>Yes</td></tr><tr><td>name</td><td>The area name people will see, for example “Maputo Central”.</td><td>Yes</td></tr><tr><td>boundaryType</td><td>The level this area belongs to, spelled exactly as you named it, for example Sub-county.</td><td>Yes</td></tr><tr><td>parentCode</td><td>The code of the area it sits inside. Leave empty for the top level.</td><td>Yes, except for the top level</td></tr><tr><td>latitude, longitude</td><td>The map position of the area.</td><td>No</td></tr></tbody></table>

{% hint style="info" %}
**Remember:** Every area needs its own code. No two rows can share a code.

An area's "parent" must be in the file too.

Do not skip a level. A ward must sit inside a sub-county, not directly inside the county.
{% endhint %}

#### 3. Upload and check

1. Drag your file onto the page, or click to choose it.
2. Optional: add a map outline file to show the real shape of each area on the citizen map. Skip this if you do not have one.
3. Look through the check results. Use the Errors tab to see any rows with problems.
4. If there are errors, fix them in Excel and select Re-upload Fixed File.
5. Select Upload to add your areas.

{% hint style="info" %}
**Note:** Only rows without errors are uploaded. Rows with errors are left out, so fix them first if you need them.
{% endhint %}

#### After your places are added

You see "Boundaries created" with the number of areas at each level. Select Back to Geography. Your hierarchy now appears on the page. Example: "3 sub-counties · 25 wards". Select Save and continue.

### If something goes wrong

<table><thead><tr><th width="304.1640625">What you see</th><th>What to do</th></tr></thead><tbody><tr><td>Bring in a boundary hierarchy to continue.</td><td>Add your places using one of the three options.</td></tr><tr><td>Add at least two levels of places.</td><td>Your hierarchy needs at least two levels with areas in them.</td></tr><tr><td>The code ‘xyz’ is used on rows ‘123’. Each boundary needs its own code.</td><td>Give each row a different code.</td></tr><tr><td>Parent "…" not found</td><td>Add the parent area to the file, or correct its code.</td></tr><tr><td>Nothing was uploaded. These codes are already in this hierarchy with a different name or parent…</td><td>An upload cannot rename or move an area. Use the existing name and parent, or a new code.</td></tr><tr><td>No boundary sheet found.</td><td>Use the downloaded template and keep the sheet name "Boundary".</td></tr><tr><td>"WORKSPACE" is reserved</td><td>Choose another hierarchy name, since some words are reserved words.</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/access/account-creation-and-onboarding-guide/geography.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
