Mapping API

Add and update mapped places (points, lines and areas) with review, trust levels and photos.

Only Jirani AI users can map. Use this API with your own Jirani AI account to send the places you map: health facilities, schools, markets, water points and transport stops (points), roads, rivers and pipes (lines), and market areas, campuses or flood-prone areas (polygons). Places are stored in the same shape as Google Places, so they can be used next to Google results.

ItemValue
Base URLhttps://api1.jirani.ai/api/v1/mapping
FormatJSON over HTTPS, UTF-8; shapes are GeoJSON
Sign-inYour Jirani AI account (verified email or phone), as a Bearer token
CoordinatesWGS84 decimal degrees. In location use latitude/longitude; in GeoJSON use [longitude, latitude]

Mapping in QGIS: the same places can be drawn and edited in QGIS, with the same rules (review unless trusted, only your own places). Connect with a Jirani AI QGIS key and open the places (points), place-lines and place-areas layers; see the Jirani AI in QGIS guide.

1. Signing in

Mapping needs a Jirani AI account with a verified email or phone number (the same account as in the Jirani AI app). Sign in from your mapping tool:

POST /auth/login
Content-Type: application/json

{"email": "[email protected]", "password": "<your password>"}

(Use "phone": "+2557..." instead of email for a phone account.) Send the accessToken from the answer on every mapping request:

Authorization: Bearer <accessToken>

The access token lasts 15 minutes. Get a new one with POST /auth/refresh and body {"refreshToken": "<refreshToken>"}; each refresh returns a new refresh token, so always keep the latest. Never share your password or tokens, and never put them in a URL.

GET /mapping/me shows your account, whether your places are approved at once (autoApprove, set by Jirani AI staff for trusted mappers) and how many places you have by status. Each place belongs to the account that sent it: only you can change or remove your places, and other mappers never see who mapped a place.

2. Place types

GET /mapping/types lists every type: its type name (send this), English and Kiswahili labels, its group, the shapes it allows (geometryKinds) and whether it is also a Google Places type.

GroupTypesShapes
Healthhospital, medical_clinic, dispensary, pharmacypoint; polygon for buildings and compounds
Educationprimary_school, secondary_school, universitypoint, polygon
Shopping and foodmarket, supermarket, store, restaurant, cafe, lodgingpoint (market, supermarket, lodging also polygon)
Moneybank, atm, mobile_money_agentpoint
Transportgas_station, bus_stop, bus_station, boda_boda_stagepoint
Safety and governmentpolice, fire_station, local_government_office, ward_officepoint, polygon
Worshipchurch, mosquepoint, polygon
Utilitieswater_point, public_bathroom, power_office (points); water_pipeline, power_line (lines)as listed
Roads and waterroute (road or street), footpath, railway, drainage_channel (lines); river (line or polygon); water_body (polygon)as listed
Areasneighborhood, residential_area, forest, flood_prone_area (polygons); farm, park, sports_complex, landmarkas listed
Otherotherany

3. Sending a place

A point: send location:

POST /mapping/places
Content-Type: application/json

{
  "externalId": "TEAM-A-000123",
  "displayName": {"text": "Zahanati ya Mwenge", "languageCode": "sw"},
  "alternativeNames": [{"text": "Mwenge Dispensary", "languageCode": "en"}],
  "primaryType": "dispensary",
  "types": ["dispensary", "health"],
  "location": {"latitude": -6.77012, "longitude": 39.22671},
  "accuracyMeters": 6,
  "formattedAddress": "Sam Nujoma Road, Mwenge, Dar es Salaam",
  "shortFormattedAddress": "Sam Nujoma Road, Mwenge",
  "nationalPhoneNumber": "0700 000 000",
  "internationalPhoneNumber": "+255 700 000 000",
  "websiteUri": "https://example.org",
  "regularOpeningHours": {"weekdayDescriptions": ["Monday: 08:00–18:00", "Saturday: 08:00–13:00", "Sunday: Closed"]},
  "businessStatus": "OPERATIONAL",
  "attributes": {"operator": "Government", "beds": "12"},
  "observedAt": "2026-10-25T09:30:00+03:00"
}

A line or polygon: send geometry as GeoJSON (LineString, MultiLineString, Polygon or MultiPolygon; Point also works). You may add location to choose the place's main point, for example a market's entrance; it must be within 2 km of the shape. Without it, Jirani AI picks a point on the line or inside the polygon.

{
  "externalId": "TEAM-A-ROAD-17",
  "displayName": {"text": "Mori Road"},
  "primaryType": "route",
  "geometry": {"type": "LineString", "coordinates": [[39.2260, -6.7700], [39.2275, -6.7702], [39.2290, -6.7700]]}
}
{
  "externalId": "TEAM-A-MKT-4",
  "displayName": {"text": "Soko la Mwenge"},
  "primaryType": "market",
  "location": {"latitude": -6.76895, "longitude": 39.22805},
  "geometry": {"type": "Polygon", "coordinates": [[[39.2278, -6.7688], [39.2283, -6.7688], [39.2283, -6.7693], [39.2278, -6.7693], [39.2278, -6.7688]]]}
}
FieldRule
displayName.textRequired, 2-200 characters: the name on the sign or used locally. languageCode is sw (default) or en.
primaryTypeRequired, one type from /mapping/types, allowed for the shape you send.
location or geometryRequired: location for a point, geometry for a line or polygon. Polygon rings must be closed (first point = last point) and must not cross themselves. Up to 10,000 vertices and 400 KB per shape.
externalIdRecommended, up to 120 characters: your own ID for the place. Sending the same externalId again updates your place instead of creating a copy, so retries are safe.
typesOptional, up to 10 extra type names (letters, digits, _). The primary type is always first.
categoryOptional, one code from GET /categories, other than news, for example tourism. People who have that preference on hear about the place in the Guide. Send it empty to clear it.
alternativeNamesOptional, up to 10 other names, each with an optional languageCode.
formattedAddress, shortFormattedAddressOptional, up to 300 and 160 characters.
nationalPhoneNumber, internationalPhoneNumberOptional, digits with +, spaces, brackets or dashes.
websiteUriOptional, http:// or https://.
regularOpeningHours.weekdayDescriptionsOptional, up to 7 lines like Google's, for example "Monday: 08:00-18:00".
businessStatusOPERATIONAL (default), CLOSED_TEMPORARILY or CLOSED_PERMANENTLY.
accuracyMetersOptional GPS accuracy, 0-10,000.
attributesOptional, up to 20 text values (keys are letters, digits and _; values up to 500 characters).
observedAtOptional, when your team saw the place (ISO 8601 with time zone).
photoMediaIdsOptional, up to 10 photo IDs. Upload each photo first with POST /media/uploads (purpose: "place", address: the place name or address, never coordinates), PUT the bytes to the returned uploadUrl, then POST /media/{id}/complete, and wait until GET /media/{id} says ready. When this field is sent, your photos on the place become exactly this list.

The answer is 201 Created for a new place or 200 OK for an update (externalId is yours alone; another mapper may use the same value). place is the stored place (see section 6) and possibleDuplicates lists approved or pending places of the same type, or with the same name, within 50 m. If your place is the same as one listed, update or remove yours rather than keeping both.

4. Sending many places

POST /mapping/places/batch
Content-Type: application/json

{"places": [ {…place…}, {…place…} ]}

Up to 200 places (8 MB) per request. Each item is checked on its own, so one bad item does not stop the others. The answer gives a summary and one result per item:

{"data": {"summary": {"created": 198, "updated": 1, "failed": 1},
          "results": [{"index": 0, "ok": true, "id": "…", "externalId": "TEAM-A-000123", "created": true, "status": "pending", "possibleDuplicates": []},
                      {"index": 7, "ok": false, "externalId": "TEAM-A-000130", "error": "INVALID_LOCATION"}]}}

5. Review status

statusMeaning
pendingReceived, waiting for a Jirani AI review.
activeApproved. Approved points and polygons of service types (health, food, money, fuel, transport, shopping, schools, worship, police) are shown in Jirani AI's nearby-services lists.
rejectedNot accepted; statusReason says why. Sending it again (same externalId) submits it for review again.
removedRemoved by you or by Jirani AI.

Whether a place is open is businessStatus, not status. Jirani AI staff may mark a mapper as trusted (places approved at once) or block a mapper who sends wrong data. Staff may correct names, types or shapes; every change is recorded.

6. The stored place

Places come back in Google Places (New) shape, plus Jirani AI fields:

FieldMeaning
id, nameJirani AI ID, and places/<id> like Google's resource name.
displayName, alternativeNames, primaryType, primaryTypeDisplayName (labels in en and sw), typesAs sent.
locationThe main point.
viewportlow and high corners of the shape's bounding box.
geometryKind, geometrypoint, line or polygon, and the GeoJSON shape.
lengthMeters, areaSquareMetersFor lines and polygons.
formattedAddress, shortFormattedAddress, nationalPhoneNumber, internationalPhoneNumber, websiteUri, regularOpeningHours, businessStatusAs sent.
googleMapsUriA Google Maps link to the main point.
rating, userRatingCount, likeCount, dislikeCountFrom Jirani AI users' reviews and reactions (section 8).
photosLike Google place photos: name, mediaId, widthPx, heightPx, url and thumbnailUrl (paths on the API host), and authorAttributions (the uploader's Jirani AI name). Photos of approved places are public.
externalId, accuracyMeters, attributes, observedAt, area (the Jirani AI area containing the point)Jirani AI fields.
status, statusReason, source (Jirani AI users or Jirani AI staff), reviewedAt, createdAt, updatedAt, versionReview and history.

7. Reading and syncing

RequestReturns
GET /mapping/places?updatedSince=2026-10-01T00:00:00Z&status=pending&limit=100Your places changed since a time, oldest change first. Follow page.nextCursor with &cursor=....
GET /mapping/places/nearby?latitude=-6.77&longitude=39.23&radiusMeters=500Places already mapped near a point (all approved places, plus your pending ones), nearest first, with distanceMeters (to the nearest edge of lines and polygons) and mine. Use it before adding a place. Radius 10-5,000 m.
GET /mapping/places/{id}One place (yours, or any approved place).
PUT /mapping/places/{id}Replace one of your places (same body as creating).
DELETE /mapping/places/{id}Remove one of your places; optional body {"reason": "..."}.

8. Nearby places, reviews, likes and dislikes

Signed-in Jirani AI users can see approved places near them, review them (like Google) and like or dislike them. These requests use /api/v1/places/... (not /mapping), with the same sign-in:

RequestUse
GET /places/nearby?latitude=-6.77&longitude=39.23&radiusMeters=2000&group=health&q=zahanatiApproved places near a point, nearest first (lines and areas by their nearest edge), each with distanceMeters and viewer.reaction. Radius 10-20,000 m (default 2,000). Optional type, group (a group from /mapping/types, for example health, food, transport) and q (name). Follow page.nextCursor.
GET /places/{id}The place with rating (average, one decimal), userRatingCount, likeCount, dislikeCount, its five newest reviews, and viewer (reaction: like, dislike or null, and your own review).
GET /places/{id}/reviews?limit=20All visible reviews, newest first (follow page.nextCursor).
PUT /places/{id}/reviewAdd or change your review: {"rating": 4, "text": "Huduma nzuri.", "languageCode": "sw"}. Rating 1-5 is required; text up to 2,000 characters is optional. One review per user and place.
DELETE /places/{id}/reviewDelete your review.
PUT /places/{id}/reactionLike or dislike: {"reaction": "like"} or {"reaction": "dislike"}. One reaction per user and place; sending the other one switches it. Answers with the new likeCount and dislikeCount.
DELETE /places/{id}/reactionRemove your like or dislike.

Reviews come in Google's shape: rating, text {text, languageCode}, authorAttribution {displayName} (the reviewer's Jirani AI name), publishTime, updateTime. Jirani AI staff may hide a review that breaks the rules; hidden reviews do not count in the rating. Errors: INVALID_RATING, INVALID_REVIEW_TEXT, INVALID_REACTION (422), NOT_FOUND (404, the place is not approved).

9. Errors and limits

Errors use the usual Jirani AI envelope: {"error": {"code": "INVALID_LOCATION", ...}}.

CodeMeaning
AUTH_REQUIRED, SESSION_REVOKED (401)No token, or it expired: refresh it or sign in again.
IDENTITY_VERIFICATION_REQUIRED (403)Verify your email or phone in the Jirani AI app first.
MAPPING_BLOCKED (403)Jirani AI has stopped this account from mapping.
INVALID_DISPLAY_NAME, INVALID_LANGUAGE_CODE, PRIMARY_TYPE_REQUIRED, UNKNOWN_PRIMARY_TYPE, INVALID_TYPES, TOO_MANY_TYPES (422)Name or type problems.
LOCATION_REQUIRED, INVALID_LOCATION, INVALID_GEOMETRY, UNSUPPORTED_GEOMETRY_TYPE, GEOMETRY_TOO_LARGE, GEOMETRY_NOT_ALLOWED_FOR_TYPE, LOCATION_FAR_FROM_GEOMETRY (422)Shape problems: missing, out of range, unclosed or self-crossing polygon, too many vertices, or a shape the type does not allow (for example a road sent as a point).
INVALID_PHOTOS, TOO_MANY_PHOTOS (422)A photo is not yours, not ready, not a place photo, or on another place; or more than 10.
INVALID_ADDRESS, INVALID_PHONE_NUMBER, INVALID_WEBSITE_URI, INVALID_OPENING_HOURS, INVALID_BUSINESS_STATUS, INVALID_ACCURACY, INVALID_EXTERNAL_ID, INVALID_OBSERVED_AT, INVALID_ALTERNATIVE_NAMES, TOO_MANY_ALTERNATIVE_NAMES, INVALID_ATTRIBUTES, TOO_MANY_ATTRIBUTES (422)The field named is not valid.
VALIDATION_FAILED (422)A request parameter or the batch size is not valid.
NOT_FOUND (404)No such place, or it belongs to another mapper.
REQUEST_TOO_LARGE (413)The request is over 8 MB; send smaller batches.
RATE_LIMITED (429)More than 600 mapping requests in 10 minutes from one sign-in. Wait and retry; use batches.

Map only what you have seen yourself or may share. Places you send become Jirani AI data: Jirani AI may correct, combine or remove them, and shows approved places in Jirani AI's apps and services.