QGIS
Connect QGIS to Jirani: reports, news, announcements, mapped places and sector reports as OGC API Features layers.
This guide connects QGIS to Jirani AI so you can see news, reports, announcements and mapped places (the same places as the Mapping API) on your map, and add and edit them if your key allows it. Staff of a sector (for example a water authority) also get sector reports: the reports sent to their organization, at the exact point, which they can reply to and mark as being fixed or fixed. Section 4 lists every field of every layer.
| Item | Value |
|---|---|
| Connection type | WFS / OGC API - Features |
| URL | https://api1.jirani.ai/api/v1/qgis |
| Sign-in | User name qgis, password = your Jirani AI QGIS key |
| Coordinates | WGS84 longitude and latitude (EPSG:4326). News, reports, announcements and places are points; place-lines are lines and place-areas are areas |
| QGIS version | Tested on QGIS 3.44 |
1. Getting your key
A Jirani AI administrator creates your key. It comes to your verified email in its own email, never in the same email as this guide, or the administrator gives it to you privately. It is not in this guide.
- A key can be read only, or it can add and edit.
- Everything you do with the key is recorded under your Jirani AI account, and your account's permissions apply.
- Keys are only made for accounts with a verified email or phone number.
- Treat it like a password. If you lose it or someone else sees it, ask an administrator to revoke it and make a new one.
2. Connecting
- Open Layer to Add Layer to Add WFS / OGC API - Features Layer.
- Click New.
- Give the connection a name, for example
Jirani AI. - Enter the URL above.
- Set Version to OGC API - Features.
- Under Authentication, add a Basic configuration with user name
qgisand your key as the password. A saved configuration keeps the key out of your project file. - Click OK, then Connect.
- Choose
news,reports,announcements,places,place-linesorplace-areas, then click Add.
QGIS loads features for the area you are viewing and fetches more as you move the map.
How QGIS knows the fields
You do not need to type field names. When you add a layer, QGIS reads the layer's schema (.../collections/{layer}/schema) and builds the attribute form from it: every field, its type (text, whole number, yes/no, date and time), and which fields are read only because Jirani AI fills them in. You can see the same list in Layer Properties to Fields, and in the tables in section 4.
Drop-down lists in the form
Every field that has a fixed set of values in Jirani AI can be a drop-down list instead of a text box: place kind (only the kinds that fit the layer's shape), category, language, open or closed, country, and for announcements the groups you manage. Fields Jirani AI fills in with a fixed set of values (report event status, publication and verification, news reach, place review status) show a readable label and stay locked. The one exception is types on the place layers: it can hold several kinds, which a QGIS drop-down cannot, so type them separated by commas. Load the form once for each layer:
- Download the layer's form file: open
https://api1.jirani.ai/api/v1/qgis/collections/{layer}/style.qmlin a browser and sign in with user nameqgisand your key. For example,.../collections/places/style.qml. It is saved asjirani-ai-places.qml. - In QGIS, right-click the layer to Properties to Style (bottom-left) to Load Style..., choose the file, and tick Fields and Forms.
- Click OK. Fields now have readable names, choices are drop-down lists, required fields are marked, and the fields Jirani AI fills in are locked.
The lists come from Jirani AI when you download the file, so download it again to see new place kinds, categories or groups. Each layer's schema also lists the choices, so other GIS tools can show them. Jirani AI still checks every value when you save.
3. Addresses
All addresses start with https://api1.jirani.ai/api/v1/qgis. QGIS calls them for you; they are listed here for other tools and scripts.
| Method and address | What it does |
|---|---|
GET / | The service's landing page, with links to the rest |
GET /conformance | The OGC standards the service follows |
GET /api | A description of the service |
GET /collections | The three layers |
GET /collections/{layer} | One layer: its title, description and extent |
GET /collections/{layer}/schema | Every field of the layer, with types and which are read only |
GET /collections/{layer}/items | Features of the layer (see "Reading options" below) |
GET /collections/{layer}/items/{id} | One feature |
POST /collections/{layer}/items | Add a feature (key must allow editing) |
PUT or PATCH /collections/{layer}/items/{id} | Edit a feature (key must allow editing) |
OPTIONS on the two items addresses | Tells QGIS whether your key may add and edit |
{layer} is reports, news or announcements. {id} is the feature's id.
Reading options
These go after items?, for example items?bbox=39.1,-6.9,39.4,-6.6&limit=200.
| Option | Values | Default | Meaning |
|---|---|---|---|
bbox | minLongitude,minLatitude,maxLongitude,maxLatitude | the whole world | Only features inside this box |
datetime | one time, or start/end, in ISO 8601 (for example 2026-11-01T00:00:00Z/..); .. leaves one end open | all times | Only features created in this time |
limit | 1 to 1000 | 100 | How many features in one page |
offset | 0 or more | 0 | How many features to skip; follow the next link for the next page |
Features come newest first. The answer is GeoJSON (application/geo+json) with numberMatched (how many match), numberReturned (how many are in this page) and links. There is no filter by field (for example by category); filter in QGIS after loading.
What you send when adding or editing
A GeoJSON feature: a geometry (a Point, or a MultiPoint with one point) and properties with the fields from section 4.
{
"type": "Feature",
"geometry": {"type": "Point", "coordinates": [39.2083, -6.7924]},
"properties": {"title": "Burst pipe on Morogoro Road", "description": "Water is running across the road near the bus stop.", "category": "utilities", "language": "en"}
}
- Unknown fields are ignored, and so are the read-only fields.
- When editing, an empty field keeps its current value. You can change a value, but not clear it by emptying it.
- Text is trimmed of spaces at both ends.
4. The layers and all their fields
Columns: Add says whether a field is needed when you add a feature; Edit says whether you can change it later. Read only fields are filled in by Jirani AI, and what you send in them is ignored.
Every feature also has an id (Jirani AI's identifier, set by Jirani AI) and a geometry (its point, or for the place lines and areas, its line or area).
reports
Published public community reports, with positions rounded to about 100 m. You also see your own reports that are waiting for review; staff see all reports. Private reports and reports sent only to a sector do not appear.
| Field | Type | Add | Edit | Meaning and rules |
|---|---|---|---|---|
| point (geometry) | point | Yes | Yes | Where it happened. Shown to others rounded to about 100 m |
title | text | No | Yes | 5 to 160 characters. If empty when adding, it is made from the description |
description | text | Yes | Yes | What happened, 10 to 5000 characters |
category | text | No | Yes | One of: business, community, education, environment, events, health, news, roads, safety, tourism, utilities |
placeLabel | text | No | Yes | The place name people see, 2 to 160 characters. If empty, the coordinates are used |
language | text | No | Yes | en or sw. en if empty |
observedAt | date and time | No | Yes | When it happened. Not in the future |
eventStatus | text | Read only | ongoing, resolved or unknown | |
publicationState | text | Read only | published, or pending_review while it waits for a moderator; staff may also see hidden | |
verificationState | text | Read only | unverified, verified, disputed or false. Only moderators set it | |
createdAt | date and time | Read only | When it was sent | |
updatedAt | date and time | Read only | When it last changed |
A new report, and every edit, waits for moderator review. Others keep seeing the last approved version until then. Only the person who sent it, or an administrator, can edit it. Reports sent to a sector are edited in the Jirani AI app, not in QGIS.
news
Published news. Your account needs external publishing access, which an administrator turns on, to add news.
- National news reaches a whole country and has no point of its own, so it is drawn at the middle of its country, and many points can sit on one spot.
- Local news has its own point and a circle, and reaches people looking at a place inside that circle.
| Field | Type | Add | Edit | Meaning and rules |
|---|---|---|---|---|
| point (geometry) | point | Yes | No | For local news, the centre of the circle. National news is drawn at its country's middle. The point cannot be moved |
title | text | Yes | Yes | 5 to 160 characters |
body | text | Yes | Yes | 10 to 5000 characters |
sourceUrl | text | Yes | Yes | A link to the original, starting with https:// |
domain | text | No | Yes | The kind of news people see, for example Risk alert, 2 to 160 characters. If empty, the website name of sourceUrl is used |
language | text | No | Yes | en or sw. en if empty |
countryCode | text | No | No | For example TZ (or 255). Filled in: national news for that whole country. Empty: local news for the circle around your point |
radiusMeters | whole number | No | No | Local news only: the circle around your point, 100 to 50000 metres. 5000 if empty |
placeLabel | text | No | Yes | The place name people see, up to 160 characters. If empty for local news, the coordinates are used |
targetScope | text | Read only | national or radius (local news) | |
createdAt | date and time | Read only | When it was published |
News goes live at once: for the whole country when countryCode is filled in, or for people looking at a place inside your circle when it is empty. It can send a news alert. Check it carefully before saving. Edits are also live at once, for the same people. Who it reaches (countryCode, radiusMeters and the point) is fixed when it is published. Only the publisher or an administrator can edit it.
announcements
Announcements from public groups and from groups you belong to.
| Field | Type | Add | Edit | Meaning and rules |
|---|---|---|---|---|
| point (geometry) | point | No | Yes | The centre of the area it covers. If empty, the group's centre is used |
groupId | text | Yes | No | The group's ID: open the group in the Jirani AI web app and copy the code after /group/ in the address. You must be an owner or moderator of the group |
title | text | Yes | Yes | 5 to 160 characters |
body | text | Yes | Yes | 10 to 5000 characters |
radiusMeters | whole number | No | Yes | How far around the point it covers, 100 to 50000 metres. 1500 if empty |
pinned | yes/no | No | Yes | Keeps it at the top of the group |
linkUrl | text | No | Yes | A web link, http:// or https://, up to 2000 characters |
mapUrl | text | No | Yes | A map link, http:// or https://, up to 2000 characters |
startsAt | date and time | No | Yes | When it starts showing |
expiresAt | date and time | No | Yes | When it stops showing. Must be after startsAt |
eventAt | date and time | No | Yes | When the event happens |
groupName | text | Read only | The group's name | |
createdAt | date and time | Read only | When it was posted | |
updatedAt | date and time | Read only | When it last changed |
A new announcement notifies the group's members straight away. An edit is saved at once and notifies nobody. The author, a manager of the group or an administrator can edit it.
Dates and times can be written as 2026-11-07T14:30:00Z, 2026-11-07T14:30:00 or 2026-11-07.
places, place-lines and place-areas (mapping)
The places mapped in Jirani AI, the same as the Mapping API: places are points (shops, clinics, schools, water points), place-lines are lines (roads, paths, drains) and place-areas are areas (markets, parks, compounds). All three layers have the same fields. You see approved places and your own places in any state; moderators and administrators also see every place waiting for review.
| Field | Type | Add | Edit | Meaning and rules |
|---|---|---|---|---|
| geometry | point, line or area | Yes | Yes | Must match the layer: a point in places, a line in place-lines, an area in place-areas. An area must not cross itself |
name | text | Yes | Yes | 2 to 200 characters |
primaryType | text | Yes | Yes | The kind of place, for example dispensary, primary_school, route or footpath. The full list, and which shapes each kind allows, is in the Mapping API guide (GET /api/v1/mapping/types) |
language | text | No | Yes | sw or en, the language of the name. sw if empty |
types | text | No | Yes | More kinds, separated by commas, up to 10 |
category | text | No | Yes | A Jirani AI category, for example water or health |
address | text | No | Yes | Up to 300 characters |
phone | text | No | Yes | For example +255 712 000 111 |
website | text | No | Yes | Starting https:// or http:// |
openingHours | text | No | Yes | Days and hours separated by ;, for example Mon-Fri 08:00-17:00; Sat 09:00-13:00, up to 7 |
businessStatus | text | No | Yes | OPERATIONAL, CLOSED_TEMPORARILY or CLOSED_PERMANENTLY |
externalId | text | No | Yes | Your own ID for the place, up to 120 characters. Sending a new place with an externalId you already used updates that place |
status | text | Read only | pending (waiting for review), active (approved), rejected or removed | |
mine | yes/no | Read only | Whether you mapped it | |
createdAt | date and time | Read only | When it was mapped | |
updatedAt | date and time | Read only | When it last changed |
A new place waits for staff review before others see it, unless you are a trusted mapper; then it is approved at once. You can edit only your own places (an administrator can edit any). A blocked mapper cannot add or edit places. Your places count towards your mapper level, as in the Mapping API.
sector-reports (sector staff only)
The reports sent to your sectors, for staff of an organization such as a water authority (an administrator adds you to the sector in the admin site). The layer is listed only for sector staff. It holds public and private reports sent to your sectors, published or still waiting for review, at the exact point the reporter gave (not rounded). Other people never see this layer or these points.
You cannot add reports here (residents send them from the app) or change what the reporter wrote. You reply: fill in response, and newStatus if the problem's status changed, then save.
| Field | Type | Edit | Meaning and rules |
|---|---|---|---|
| point (geometry) | point | No | Where the problem is: the exact point when the reporter gave one (exactLocation), otherwise the rounded one |
response | text | Yes | Your reply to the reporter, 10 to 5000 characters, for example Technician sent; repair today. It is saved as your sector's update on the report and the reporter is told "<sector> replied to your report". Reads back empty after saving |
newStatus | text | Yes | ongoing (being fixed) or resolved (fixed). Needs a response. The report's eventStatus changes when the reporter or a moderator accepts your reply |
title, description, category, placeLabel | text | Read only | What the reporter wrote |
sectorName | text | Read only | Which of your sectors it was sent to |
visibility | text | Read only | public or private (only the reporter and the sector see it) |
publicationState | text | Read only | published, or pending_review while moderators check it. You can reply only to published reports |
verificationState | text | Read only | As in reports |
eventStatus | text | Read only | ongoing, resolved or unknown: the accepted status |
confirmations | whole number | Read only | Neighbours who said they also saw it |
photos | whole number | Read only | Photos on the report (open them in the Sector API or the app) |
exactLocation, accuracyMeters | yes/no, number | Read only | Whether the point is exact, and the phone's GPS accuracy |
observedAt, createdAt, updatedAt | date and time | Read only | When it was seen, sent and last changed |
lastResponse, lastResponseAt | text, date and time | Read only | Your sector's latest reply and when it was sent |
lastResponseStatus | text | Read only | The status that reply proposed |
lastResponseState | text | Read only | submitted (waiting for the reporter or a moderator), reviewed (accepted), rejected or withdrawn |
Tip: style the layer by eventStatus (or lastResponseState) to see at a glance what is open, being fixed and fixed, and filter by createdAt to measure response times.
5. Adding and editing in QGIS
Adding: select the layer, click Toggle Editing, then Add Point Feature (or Add Line Feature / Add Polygon Feature on place-lines and place-areas), draw on the map, fill in the form and Save Layer Edits. Leave the read-only fields empty.
Editing: toggle editing, change the form or move the point or the shape's corners (not for news), then Save Layer Edits.
Replying to a sector report: on sector-reports, toggle editing, open the feature's form (Identify or the attribute table), write response, pick newStatus if it changed, then Save Layer Edits. Each save with a new response is one reply.
6. What QGIS cannot do
- Deleting: nothing can be deleted from QGIS. Use the Jirani AI app or ask an administrator.
- Other shapes: news, reports and announcements take only points. Lines and areas are for places, on
place-linesandplace-areas. - Photos: photos cannot be added from QGIS. Add photos to places with the Mapping API or in the app.
7. If something goes wrong
| What you see | Error | What to do |
|---|---|---|
| QGIS keeps asking for a user name and password | AUTH_REQUIRED | The key is wrong or was revoked. Ask an administrator for a new one |
| The editing buttons are greyed out, or a save is refused | GIS_KEY_READ_ONLY | Your key is read only. Ask an administrator for a key that can edit |
| A save fails on a news or announcement feature | FORBIDDEN | You do not have permission: news needs publishing access, an announcement needs a group you manage, and only the author can edit |
| A save fails with a field problem | VALIDATION_FAILED | A required field is missing, too short or too long, or a value is not allowed. Check the tables in section 4 |
| Adding a report or news fails | EVENT_LOCATION_REQUIRED | Click a point on the map before saving |
| Adding an announcement fails | GROUP_REQUIRED | Fill in groupId |
| A line or area is refused | GEOMETRY_MUST_BE_POINT | Draw a single point |
| A place is refused because of its shape | GEOMETRY_WRONG_LAYER | Points go in places, lines in place-lines, areas in place-areas |
| A place's kind is refused | UNKNOWN_PRIMARY_TYPE or GEOMETRY_NOT_ALLOWED_FOR_TYPE | Use a kind from the Mapping API list, with a shape that kind allows |
| An area is refused | INVALID_GEOMETRY | The area crosses itself. Fix the corners |
There is no sector-reports layer | You are not staff of a sector. Ask an administrator to add you to your organization's sector | |
| A sector reply is refused | RESPONSE_REQUIRED | Write a response of at least 10 characters (also when you only change newStatus) |
| A sector reply is refused | REPORT_NOT_PUBLISHED | The report is still waiting for moderator review; reply after it is published |
Adding to sector-reports fails | SECTOR_REPORTS_COME_FROM_THE_APP | Reports come from residents in the app; you can only reply |
| Adding or editing places fails | MAPPING_BLOCKED | Your mapping is blocked. Contact an administrator |
| A date is refused | INVALID_DATE | Use one of the date formats in section 4 |
| Moving a news point fails | NEWS_LOCATION_FIXED | News points cannot be moved. Press Cancel Edits on that change |
| Editing a report sent to a sector fails | SECTOR_REPORT_EDITED_IN_APP | Edit it in the Jirani AI app |
| A feature cannot be found | NOT_FOUND | It was deleted, or you cannot see it |
| An empty layer opens with no fields | Your QGIS may be too old to read the layer description. Update QGIS, or use it once the layer has a feature |
Save limits: up to 1200 changes every 10 minutes per key.
