Skip to content

Humanitarian Data HDX OSM geoBoundaries

github-actions[bot] edited this page Nov 2, 2026 · 2 revisions

This page is generated from the repository on every merge to main; changes made here are overwritten.

add_incident_point

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.

add_point_layer

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.

fetch_building_footprints (two-phase)

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_fts_funding_data (network-only)

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.

fetch_geoboundaries (two-phase)

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.

fetch_hdx_admin_boundaries (two-phase)

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_osm_features (network-only)

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_worldpop_population (two-phase)

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.

ingest_osm_features (two-phase)

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_hdx_datasets (network-only)

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.

Clone this wiki locally