Repository navigation
Humanitarian Data HDX OSM geoBoundaries
This page is generated from the repository on every merge to
main; changes made here are overwritten.
Plot a single real-world incident/event as a labeled point on the map, using consistent professional styling (red marker, white-background/red-text label). Adds to a shared 'Incidents' layer, creating it on first use. Only ever call this with real, verified data -- if the coordinates or date aren't already known, use search_web/geocode_and_enrich to find them first; never invent placeholder values. Set severity when it's known (e.g. security incident classification) so apply_categorized_style/apply_graduated_symbol_style can later distinguish incident types on the map instead of every point looking identical. For conflict/security incidents, also set event_type (+ sub_event_type) using ACLED's controlled taxonomy when the source classification maps to it; for explosive-hazard incidents, set hazard_type (+ contamination_status) using the IMSMA/IMAS-style vocabulary. Both are optional and validated -- an unrecognized value comes back as a warning, not a rejected point. If the incident spans a period rather than one instant (e.g. a hazard active over days, a multi-day event), also set event_start/event_end alongside the existing date field -- additive, not a replacement, so date stays freeform for single-date sources. last_verified records when the data was last confirmed, separate from when the incident itself occurred.
| Parameter | Type | Required | Description |
|---|---|---|---|
lat |
number | yes | Latitude in decimal degrees (WGS84). |
lon |
number | yes | Longitude in decimal degrees (WGS84). |
date |
string | yes | Real, verified date of the incident (e.g. '2026-03-14'). |
description |
string | yes | Short, factual description of the incident. |
severity |
string | no | Optional severity/category label, e.g. 'High', 'Security', 'Flood'. Free text -- use whatever classification the source data uses. |
event_type |
string | no | Optional ACLED-style controlled event type: one of ['Battles', 'Protests', 'Riots', 'Explosions/Remote violence', 'Violence against civilians', 'Strategic developments']. |
sub_event_type |
string | no | Optional ACLED-style sub-event type, valid within the chosen event_type. |
hazard_type |
string | no | Optional IMSMA/IMAS-style explosive-hazard type: one of ['Landmine - Anti-Personnel', 'Landmine - Anti-Vehicle', 'Unexploded Ordnance (UXO)', 'Abandoned Ordnance (AXO)', 'Improvised Explosive Device (IED)', 'Cluster Munition Remnant', 'Booby Trap']. |
contamination_status |
string | no | Optional IMSMA/IMAS-style contamination status: one of ['Confirmed Hazardous Area', 'Suspected Hazardous Area', 'Cleared']. |
event_start |
string | no | Optional ISO date (YYYY-MM-DD) the incident/hazard started, when it spans a period rather than one day. |
event_end |
string | no | Optional ISO date (YYYY-MM-DD) the incident/hazard ended, when it spans a period rather than one day. |
last_verified |
string | no | Optional ISO date (YYYY-MM-DD) this data was last confirmed accurate -- distinct from when the incident occurred. |
Create a new point layer (or append to an existing one with the same name) from a LIST of real, verified locations in a SINGLE call -- e.g. embassies, offices, facilities, or any set of named points of interest. Always prefer this over calling add_incident_point repeatedly when plotting more than one location -- one call per point will exhaust the agent's step limit on anything but a short list. Gather every location first (search_web/gemini_grounded_search/geocode_and_enrich), then call this once with the full list. Only ever use real, verified coordinates -- never invent placeholder values. Set category per point when it's known (e.g. incident severity/type) so apply_categorized_style can later distinguish them on the map. For conflict/security points, also set event_type (+ sub_event_type) using ACLED's controlled taxonomy when the source classification maps to it; for explosive-hazard points, set hazard_type (+ contamination_status) using the IMSMA/IMAS-style vocabulary. Both are optional and validated -- an unrecognized value comes back as a per-point warning, not a rejected point. If a point spans a period rather than one instant, also set event_start/event_end (additive alongside any date-like field in description); last_verified records when the data was last confirmed. If you're plotting incidents, threats, or other security-related points and haven't actually gathered them from a real source in this conversation (search_web/gemini_grounded_search/geocode_and_enrich/geocode_batch, or data the user supplied directly), do not call this tool with invented data -- say plainly in your chat response that you don't have verified locations for that, instead of fabricating a plausible-looking dataset. A point layer feeds directly into exported maps and reports, where fabricated content is far more likely to be trusted and acted on than the same claim in chat.
| Parameter | Type | Required | Description |
|---|---|---|---|
layer_name |
string | yes | Name for the layer, e.g. 'Foreign Embassies'. |
points |
array[object] | yes | List of points to add, e.g. [{"lat": 31.95, "lon": 35.93, "name": "Embassy of France", "description": "Amman", "category": "High"}]. |
crs |
string | no | CRS the point coordinates are in, e.g. "EPSG:3857" or "EPSG:32636". Omit ONLY when the coordinates are already lon/lat degrees. If the user gave projected coordinates (large numbers such as 4902068, 1799912), pass them UNCHANGED with their CRS (the project CRS unless the user says otherwise) -- the code converts them exactly. NEVER convert coordinates yourself. |
crs_stated_by_user |
boolean | no | true ONLY when the user's own message named the CRS of these coordinates (for example 'in EPSG:3857'). When the user gave projected numbers WITHOUT a CRS, pass the project CRS and leave this false: if that CRS is not the project's the tool asks the user instead of placing the point. |
Download building footprint polygons for an area of interest from Microsoft's Global ML Building Footprints dataset (1B+ buildings, 225 countries/regions, CDLA Permissive 2.0 license) -- for baseline digitization where no local building-footprint data exists (e.g. in-limit boundary work), NOT for damage assessment against a specific fresh image (use calculate_raster_change_detection for that instead; see the result's baseline_caveat for the exact wording on how current this dataset is). country_name is free text matched against the dataset's own location list (NOT an ISO3 code -- this dataset isn't indexed that way); an ambiguous or unmatched name returns candidate matches instead of guessing.
| Parameter | Type | Required | Description |
|---|---|---|---|
country_name |
string | yes | Country name, e.g. 'Yemen'. Matched against the dataset's own location names, not an ISO3 code. |
bbox |
array[number] | yes | [south, west, north, east] in WGS84 degrees -- footprints are cropped to this area, not the whole country. |
max_features |
integer | no | Safety cap on returned features. Defaults to 5000; if exceeded, results are truncated (not silently dropped) and truncated=true is reported. |
allow_large_download |
boolean | no | Set true ONLY after the user agreed to a download above their size threshold. |
Fetch humanitarian funding data from OCHA's Financial Tracking Service (FTS) for a country's response plan -- requirements, funding received, coverage percentage, and the funding gap. If year/plan_id are omitted, auto-selects the most recent plan and reports that it did so; if more than one plan matches (a country can run several concurrent plans in the same year, e.g. a regional migrant response alongside the main response plan), returns the candidate list instead of guessing which one you meant -- call again with plan_id set to one of those. Funding figures are a live snapshot from FTS, not a final/certain total -- state that when presenting them, the same way you would any other point-in-time data.
| Parameter | Type | Required | Description |
|---|---|---|---|
country_iso3 |
string | yes | 3-letter ISO country code, e.g. 'YEM'. |
year |
integer | no | Response plan year, e.g. 2024. Omit to auto-select the most recent. |
plan_id |
integer | no | A specific FTS plan ID (from a prior call's plan list) to fetch directly. |
Download administrative boundaries from geoBoundaries API. A file larger than the user's download-size setting is not fetched until the user agrees: then call again with allow_large_download=true.
| Parameter | Type | Required | Description |
|---|---|---|---|
iso3 |
string | yes | |
admin_level |
string | yes | |
allow_large_download |
boolean | no | Set true ONLY after the user agreed to a download above their size threshold. |
Download OCHA's Common Operational Dataset - Administrative Boundaries (COD-AB) for a country from HDX -- the authoritative humanitarian source for admin boundaries, carrying real P-codes (the OCHA/HDX standard admin-unit code, e.g. 'YE12') as an attribute, unlike fetch_geoboundaries which doesn't publish P-codes at all. Reports which attribute field holds the P-code (pcode_field in the result) so it can be passed straight to unit_name_field/presence_admin_field for a reliable join in calculate_severity_index/calculate_presence_gap instead of fragile name-string matching. COD-AB coverage isn't universal -- if no dataset exists for a country, fall back to fetch_geoboundaries (broader coverage, but no P-codes).
| Parameter | Type | Required | Description |
|---|---|---|---|
iso3 |
string | yes | 3-letter ISO country code, e.g. 'YEM'. |
admin_level |
string | no | Admin level, e.g. 'ADM1', 'ADM2'. Defaults to 'ADM1'. |
allow_large_download |
boolean | no | Set true ONLY after the user agreed to a download above their size threshold. |
Fetch OpenStreetMap vector features via Overpass API for a bounding box.
| Parameter | Type | Required | Description |
|---|---|---|---|
key |
string | yes | |
value |
string | yes | |
bbox |
array[number] | yes |
Fetch a country's gridded population raster from WorldPop (open, free population data at ~100m resolution) and load it as a layer -- an open-data approximation of what ArcGIS's Business Analyst extension provides with proprietary demographic data. ALWAYS pass extent_layer (a layer covering the area of interest, e.g. the catchment or admin boundary) or bbox: without either the call is refused, because the WHOLE country would be downloaded (100MB-1GB+, minutes) -- allow_whole_country=true overrides that, only after the user agreed. With one, only that area plus a ~2 km margin is fetched and the layer is named population_area. After loading, use estimate_population_exposure to sum population within a specific area.
| Parameter | Type | Required | Description |
|---|---|---|---|
iso3 |
string | yes | 3-letter ISO country code, e.g. 'YEM'. |
year |
string | no | Population year, e.g. '2020'. Omit to use the most recent available. |
extent_layer |
string | no | Name of a project layer whose extent is the area to fetch (preferred -- handles any CRS). |
bbox |
array[number] | no | Alternative to extent_layer: [min_lon, min_lat, max_lon, max_lat] in WGS84 degrees. |
allow_whole_country |
boolean | no | Set true ONLY after the user agreed to download the whole country file (worldpop.org cannot send just a window; the real size is shown first). Without extent_layer/bbox and without this, the tool refuses. |
Download OpenStreetMap vector features via Overpass API (e.g. key='amenity', value='hospital', or value='hospital|clinic|doctors', or key='highway', value='primary|secondary') for a bounding box or around a center coordinate and directly add them as a new vector layer to the active QGIS project. Use this whenever you need to ingest facilities, infrastructure, or road networks into an empty or new project.
| Parameter | Type | Required | Description |
|---|---|---|---|
key |
string | yes | OSM tag key, e.g. 'amenity', 'highway', 'building' |
value |
string | yes | OSM tag value or regex pipe-separated values, e.g. 'hospital', 'hospital |
bbox |
array[number] | no | Optional bounding box [south, west, north, east] |
center_lat |
number | no | Optional center latitude for radius search |
center_lon |
number | no | Optional center longitude for radius search |
radius_km |
number | no | Optional search radius in km around center (default: 10 km) |
layer_name |
string | no | Optional name for the created QGIS vector layer |
Search Humanitarian Data Exchange (HDX) for datasets by query. Results are ranked: each has a score and plain reasons about its licence (open, none stated, not open), how recently it changed and whether it lists the country asked for and has a usable file. Pass country (name or ISO3) to prefer data sets about it.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | yes | |
limit |
integer | no | |
country |
string | no | Optional country name or ISO3 code; data sets that list it rank higher. |
Cartogen AI 1.18.5 · generated from the repository at commit 7cef7bc450 on 2026-11-18 · this wiki is rebuilt on every merge to main; edits made in the browser are overwritten, so correct the source files instead.
Get started
How it works
- Architecture overview
- The agent loop
- Threads, tasks and Stop
- Tools and routing
- Providers and networking
- Memory, state and results
- Guards and honesty checks
- The dock and dialogs
- Processing provider
Tools and data
- Tool reference
- AI Imagery Feature Extraction
- Data Analysis & Prediction
- Database & Workflows
- Export & Reporting
- Humanitarian Data (HDX / OSM / geoBoundaries)
- Humanitarian Logistics
- Monitoring & Scheduling
- Print Layouts
- Project Management
- Raster
- Reporting & Document Analysis
- Satellite Imagery & Vision
- Styling & Labeling
- System, Search & Scripting
- Task & Memory Management
- Vector & Geoprocessing
- More tools, by module
- Task register
- External data sources
Humanitarian GIS
Security and privacy
Develop
Project