Docs contribution offer: plain-language "how to read this data" explainer

[AlexFC0810]

Salaam — long-time consumer of this dataset. Your pipeline updates faster than anyone explains what the endpoints mean, how to consume the API correctly, or how to state the documented undercount caveats honestly — which means non-specialists mis-cite data you've carefully caveated.

We drafted a plain-language explainer for the casualty dataset: what each endpoint contains, how to consume the API (instead of scraping raw MoH PDFs), and a clear section restating your own documented limitations. Offering it as a community contribution to your docs — take it as-is, edit freely, or tell us the format you'd prefer. Everything links back to your portal; we will never build a competing dataset or restate your numbers as our own.

Also: would standardized reuse/credit language help you? Happy to draft that too. — Alex

The draft explainer (full text)

How to Read the Palestine Datasets (Tech for Palestine): A Plain-Language Explainer

DRAFT — community docs contribution, offered for the maintainers' edits.
This is a plain-language walk-through of the Palestine Datasets published by Tech for Palestine, written by an outside consumer of the data as a proposed contribution to their documentation. It restates the maintainers' own words; it does not add, re-derive, or re-verify any figure. Every dataset, endpoint, and limitation below is theirs. Please take it as-is, edit freely, correct anything we got wrong, or tell us the format you would prefer. Everything links back to the official portal. We will never build a competing dataset or restate their numbers as our own.

What this document is NOT: not a data source, not an independent verification, not a re-publication of the datasets, and not advice of any kind. It is a reading guide that points back to the primary source for every claim.

---

About this explainer

Purpose: Tech for Palestine's data pipeline updates faster than most non-specialists can keep up with what each endpoint means, how to consume the API correctly, or how to state the documented undercount caveats honestly. This explainer exists so that people citing the data cite it the way the maintainers ask it to be cited — with the source attributed and the limitations restated.

Sourcing rule for this document: every factual claim, number, field name, endpoint, and quotation below is cited to a specific page on the official portal or GitHub repository that was fetched on the access date shown. Where a value was not confirmed against a fetched source, it is marked unknown rather than guessed.

Access date for all fetches in this document: 2026-07-10.

Primary sources (all fetched 2026-07-10):

#	What it is	URL
S1	Datasets index	https://data.techforpalestine.org/docs/datasets/
S2	Killed in Gaza dataset docs	https://data.techforpalestine.org/docs/killed-in-gaza/
S3	Daily Casualties (Gaza) docs	https://data.techforpalestine.org/docs/casualties-daily/
S4	Daily Casualties (West Bank) docs	https://data.techforpalestine.org/docs/casualties-daily-west-bank/
S5	Press Killed in Gaza docs	https://data.techforpalestine.org/docs/press-killed-in-gaza/
S6	Summary dataset docs	https://data.techforpalestine.org/docs/summary/
S7	Infrastructure Damaged docs	https://data.techforpalestine.org/docs/infrastructure-damaged/
S8	Versioning guide	https://data.techforpalestine.org/docs/guides/versioning/
S9	Example Usage page	https://data.techforpalestine.org/docs/examples/
S10	Contributing guide	https://data.techforpalestine.org/docs/guides/contributing/
S11	Contact page	https://data.techforpalestine.org/docs/contact/
S12	GitHub repository README	https://github.com/TechForPalestine/palestine-datasets
S13	LICENSE (Unlicense)	https://github.com/TechForPalestine/palestine-datasets/blob/main/LICENSE
S14	Live summary endpoint (v3)	https://data.techforpalestine.org/api/v3/summary.json

---

1. What this project is, in one paragraph

Palestine Datasets is an open-source project by the Tech for Palestine collective that publishes machine-readable datasets — as JSON and CSV files served from versioned, static API endpoints — documenting, in the repository's own words, "the human toll of Israel's hostilities across Palestine since Oct 7, 2023" (S12, GitHub README, fetched 2026-07-10). It is a static, CI-built data site, not a live query backend: you fetch pre-built files at fixed URLs. The data and code are released into the public domain under the Unlicense (S13, fetched 2026-07-10; see §6). The maintainers state the purpose plainly on their Example Usage page: "We're providing this data in the hopes it will help you tell a story about what Palestinians are going through" (S9, fetched 2026-07-10).

---

2. The six datasets, in plain language

The datasets index (S1, fetched 2026-07-10) documents six datasets. Here is what each one contains and where to get it. All endpoint URLs below were read from the dataset docs pages on 2026-07-10.

2.1 Killed in Gaza — named individuals

What it contains: a list of named individuals killed in Gaza, compiled from Gaza's Ministry of Health releases. Per the dataset docs (S2, fetched 2026-07-10), each record carries these fields:

Field	Meaning (per S2)
name	Original Arabic name
en_name	English translation of the name
id	Unique identifier
dob	Date of birth (YYYY-MM-DD, or empty)
sex	m / f
age	Numeric age
source	Data origin — Ministry of Health, Public Submission, Judicial Committee, or Unknown (v2 only; see §5)
update	Update number (v3 only)

Endpoints (S2, fetched 2026-07-10):

• Full CSV: https://data.techforpalestine.org/api/v3/killed-in-gaza.csv
• Full minified JSON: https://data.techforpalestine.org/api/v3/killed-in-gaza.min.json
• Paged JSON (v2): https://data.techforpalestine.org/api/v2/killed-in-gaza/page-[1..N].json
• Name-frequency helper: https://data.techforpalestine.org/api/v2/killed-in-gaza/name-freq-en.json

Scale (as documented on the fetched page, S2, 2026-07-10): the docs page stated a dataset of 60,198 names as of its most recent list update, described as the ninth update covering through 2025-07-31. This is the figure the docs page displayed on the access date; treat the live endpoints (§4) and the docs page as authoritative over this explainer for any current number.

Read this dataset with its own headline caveat (verbatim, S2, fetched 2026-07-10): "The names & numbers we publish here are not fully representative of the human toll," and "this list will be an undercount." The full, quoted limitations are in §3.1 — do not cite this dataset without them.

2.2 Press Killed in Gaza — journalists

What it contains: a list of journalists known to have been killed in Gaza since October 7, 2023. Per S5 (fetched 2026-07-10), each record has:

Field	Meaning (per S5)
name	Original Arabic name from the source list
name_en	English translation
notes	Agency affiliation and available detail on circumstances of death

Endpoints (S5, fetched 2026-07-10):

• Minified JSON: https://data.techforpalestine.org/api/v2/press_killed_in_gaza.min.json
• Unminified JSON: https://data.techforpalestine.org/api/v2/press_killed_in_gaza.json
• CSV: https://data.techforpalestine.org/api/v2/press_killed_in_gaza.csv

Source & update trigger (verbatim, S5, fetched 2026-07-10): "The file is updated when a new list is released by Gaza's Government Media Office or when we receive incremental updates about new individual incidents."

Documented limitation (verbatim, S5, fetched 2026-07-10): "As of writing, it includes photos for just over half of the list" — i.e., photographic documentation is incomplete.

2.3 Daily Casualties — Gaza — the daily time series

What it contains: daily killed-and-injured figures for Gaza, one record per report day since 2023-10-07. Core fields per S3 (fetched 2026-07-10):

Field	Meaning (per S3)
report_date	YYYY-MM-DD
report_source	mohtel, gmotel, unocha, or missing (see below)
report_period	24, 48, or 0 hours
killed / killed_cum	daily / cumulative killed
injured / injured_cum	daily / cumulative injured
killed_children_cum, killed_women_cum	demographic cumulative breakdowns
civdef_killed_cum, med_killed_cum, press_killed_cum	civil-defence, medical, press cumulative
massacres_cum, famine_cum, aid_seeker_killed_cum	specialized cumulative categories
ext_-prefixed variants	extrapolated values used when data is missing (see §3.3)

Endpoints (S3, fetched 2026-07-10):

• Minified JSON: https://data.techforpalestine.org/api/v2/casualties_daily.min.json
• Unminified JSON: https://data.techforpalestine.org/api/v2/casualties_daily.json
• CSV: https://data.techforpalestine.org/api/v2/casualties_daily.csv

Update timing (per S3, fetched 2026-07-10): updated each morning, Eastern Time. Sources: primary is the Gaza Ministry of Health Telegram channel (mohtel); secondary is the Government Media Office Telegram (gmotel); where neither is available the record is marked missing.

Key caveat you must carry (verbatim, S3, fetched 2026-07-10): "The numbers we publish here are not fully representative of the human toll of Israel's actions in Gaza." See §3.2 for the indirect-deaths caveat.

2.4 Daily Casualties — West Bank

What it contains: daily killed and injured in the West Bank since 2023-10-07, plus child breakdowns and a cumulative count of Israeli settler attacks. A distinctive feature: this dataset separates verified values (confirmed by UN OCHA personnel) from unverified/flash values. Fields per S4 (fetched 2026-07-10) include report_date; the verified.* object (killed, killed_cum, injured, injured_cum, and child variants, each optional); top-level unverified cumulatives (killed_cum, injured_cum, child variants); settler_attacks_cum; and flash_source ("un" or "fill").

Endpoints (S4, fetched 2026-07-10):

• Minified JSON: https://data.techforpalestine.org/api/v2/west_bank_daily.min.json
• Unminified JSON: https://data.techforpalestine.org/api/v2/west_bank_daily.json
• CSV: https://data.techforpalestine.org/api/v2/west_bank_daily.csv

Source (per S4, fetched 2026-07-10): the maintainers state "We depend on UN OCHA" for West Bank data, distinguishing verified data (independently confirmed by UN OCHA personnel) from flash-updates (reported but "not yet verified").

Documented limitations (verbatim, S4, fetched 2026-07-10):

• "Verified values will lag the ones that come from Flash Updates"
• "Flash Updates occasionally miss days"
• As of a stated date the docs give as March 25, these updates "are only available for the West Bank on a weekly basis"

(Practical reading: when you need the most-defensible West Bank figure, prefer the verified.* fields and note they lag; the top-level unverified cumulatives are timelier but, by the maintainers' own framing, not yet confirmed.)

2.5 Infrastructure Damaged — Gaza

What it contains: daily cumulative counts of damaged/destroyed civilian infrastructure in Gaza. Per S7 (fetched 2026-07-10) the categories include civic buildings (destroyed); educational buildings (destroyed and damaged); places of worship — mosques and churches (destroyed and damaged); and residential units (destroyed). Each report carries a YYYY-MM-DD date; most fields are optional and omitted when no value exists, and the dataset provides both official counts and ext_ (extrapolated) versions.

Endpoints (S7, fetched 2026-07-10):

• Minified JSON: https://data.techforpalestine.org/api/v3/infrastructure-damaged.min.json
• Unminified JSON: https://data.techforpalestine.org/api/v3/infrastructure-damaged.json

Source (per S7, fetched 2026-07-10): the "Government Media Office (GMO) in Gaza."

Documented limitations (verbatim, S7, fetched 2026-07-10):

• "Reports are provided roughly once every week (as of 2024) and it's unclear how frequently government officials are updating these numbers between reports."
• "For that reason they should be treated as estimates, especially given the magnitude and the difficulty for non-combatants to enter certain regions in Gaza where Israeli forces are present."
• The docs also note a classification shift in May regarding how mosques were categorized, with unclear cause — a reminder that category definitions can change over time.

The docs page also situates the data with this framing (verbatim, S7, fetched 2026-07-10): "Gaza is nearly entirely destroyed. By some estimates over 90% of buildings and infrastructure have been targeted in some way." (Note: the "over 90%" phrasing is attributed by the docs to unnamed "some estimates," not to this dataset's own counts — cite it as the maintainers frame it, not as a measured value from this dataset.)

2.6 Summary — the cross-dataset snapshot

What it contains: the latest cumulative values pulled from the other datasets into a single small file — the easiest single call for a current headline number. Per S6 (fetched 2026-07-10), it is organized into sections:

• gaza — reports, last_update, and killed (with total, children, women, press, medical, civil_defence), injured.total, massacres, famine (total, children), aid_seeker (killed, injured).
• west_bank — reports, last_update, killed (total, children), injured (total, children), settler_attacks.
• known_killed_in_gaza — records, pages, page_size, last_update, includes_until (coverage end date), and male/female demographic breakdowns by senior / adult / child / no_age.
• known_press_killed_in_gaza — records.

Endpoints (S6, fetched 2026-07-10):

• v3 minified: https://data.techforpalestine.org/api/v3/summary.min.json
• v3 full: https://data.techforpalestine.org/api/v3/summary.json
• v2 (previous): https://data.techforpalestine.org/api/v2/summary.json

Update frequency (verbatim, S6, fetched 2026-07-10): the file "is updated whenever the other datasets are updated (typically daily)." One sync caveat (verbatim, S6): "This value is reported independently and while we aim to keep it in sync, the name list updates may lag the daily casualties counts."

A live read of this endpoint (S14, fetched 2026-07-10): on the access date, summary.json reported gaza.last_update = 2026-07-09 and known_killed_in_gaza.last_update = 2025-08-17 with includes_until = 2025-07-31. The gap between those two dates is the single most important thing to understand about this data (see §3.4): the daily aggregate totals move almost daily, but the named-individuals list is updated far less often. Specific numeric values from this live read are intentionally not restated here as standing facts, because they change; fetch the endpoint yourself and cite it with your own access date.

---

3. Their documented limitations, restated honestly (READ THIS BEFORE CITING ANY NUMBER)

This is the section that matters most. The maintainers have been careful to caveat their data; anyone citing it should carry those caveats forward. Everything in this section is quoted or closely paraphrased from their own docs, with the source and access date attached. Nothing here is our assessment of the data's accuracy — it is their stated account of what the data does and does not capture.

3.1 The Killed-in-Gaza list is an explicit undercount

The dataset docs (S2, fetched 2026-07-10) reproduce the source Ministry's statement that the list excludes the following categories (verbatim):

1. "The missing persons and the bodies of those trapped under the rubble"
2. "The unidentified people who arrived at hospitals"
3. "The unidentified persons whose bodies were handed over by the occupation"
4. "Those who were buried by their families without passing through hospitals"
5. "The victims in Gaza and North Gaza … after the date of stopping the information system in November"

The maintainers add, verbatim (S2, fetched 2026-07-10): "The names & numbers we publish here are not fully representative of the human toll," and "this list will be an undercount."

Plain-language meaning: the named list is a floor, not a total. People trapped under rubble, the unidentified, those buried without passing through a hospital, and deaths after the information system paused in November are not in this list. Cite it as "at least this many named individuals, per Gaza's Ministry of Health, which itself states the list is an undercount."

3.2 Daily Gaza casualties count only direct deaths

Per S3 (fetched 2026-07-10): "The numbers we publish here are not fully representative of the human toll of Israel's actions in Gaza." The docs explain that the Ministry records "only direct casualties of war," while indirect deaths — from malnutrition, inadequate care, or war-related complications — are, in the docs' phrasing, "documented but not recorded as martyrs" and so are not in the direct-casualty totals. The docs also note that demographic breakdowns update irregularly (weekly in 2024, bi-weekly from August 2024, monthly from January 2025), so a demographic sub-count may be less current than the top-line total.

Plain-language meaning: deaths from starvation, untreated illness, and collapsed healthcare are largely outside the daily direct-casualty totals. The true toll, by the maintainers' own framing, is higher than these figures.

3.3 "Extrapolated" (ext_) fields are estimates, not reports

Both the Daily Casualties (S3) and Infrastructure Damaged (S7) datasets expose ext_-prefixed fields (fetched 2026-07-10). Per S3, extrapolated fields "use averaging when both daily and cumulative data" are unavailable. Per S7, infrastructure figures "should be treated as estimates."

Plain-language meaning: a field beginning ext_ is the maintainers' filled-in estimate for a gap in the underlying reporting, not a value that was directly reported. If you need only directly-reported values, use the non-ext_ fields and expect gaps; if you need a continuous series, use the ext_ fields and label them as extrapolated.

3.4 The named list and the daily totals are on different clocks

From the live summary read (S14, fetched 2026-07-10) and the summary docs (S6): the Gaza daily aggregate (gaza.last_update) advances almost daily, while the named Killed-in-Gaza list (known_killed_in_gaza.last_update / includes_until) is refreshed only when the Ministry issues a new named list — far less often. The two numbers therefore will not match, and that is expected, not an error.

Plain-language meaning: never compare "number of named individuals" against "cumulative killed" as if they should be equal. The named list lags the aggregate by design. State each with its own coverage date.

3.5 Data quality is bounded by upstream sources the project does not control

The Gaza datasets derive substantially from Gaza's Ministry of Health and Government Media Office reporting; the West Bank dataset depends on UN OCHA (S2, S3, S4, S5, S7, fetched 2026-07-10). The maintainers attribute their figures to those sources rather than presenting them as independently verified. The overarching disclaimer in the repository README is unambiguous (verbatim, S12, fetched 2026-07-10): "These datasets do not fully reflect the impact of the genocide in Gaza, please read more about how we source our Gaza data and the limitations."

Plain-language meaning: when you cite these numbers, attribute them the way the maintainers do — to the Ministry of Health / Government Media Office / UN OCHA — and carry the undercount caveat. Do not restate them as independently verified totals.

---

4. How to consume the API correctly (a small, correct example)

The API is static files at versioned URLs — there is no query language, no API key, and (per the docs read on 2026-07-10) no documented authentication step; if you require rate limits or terms-of-service specifics, treat those as unknown from the pages fetched here and confirm with the maintainers (§7). You fetch a file and read it. The single most useful call for a current headline is the summary endpoint.

A minimal, correct read (illustrative; endpoint per S6/S14, fetched 2026-07-10):

# Fetch the cross-dataset summary (small file, updated ~daily)
curl -s https://data.techforpalestine.org/api/v3/summary.json

import urllib.request, json

URL = "https://data.techforpalestine.org/api/v3/summary.json"
with urllib.request.urlopen(URL) as r:
    summary = json.load(r)

# Always read the coverage dates alongside any figure, and cite them:
gaza_as_of = summary["gaza"]["last_update"]            # daily aggregate clock
names_as_of = summary["known_killed_in_gaza"]["last_update"]  # named-list clock
# Present each number WITH its own as-of date and the undercount caveat (see §3).

Doing it right — a short checklist drawn from the maintainers' own docs (S2, S3, S6, S8; fetched 2026-07-10):

1. Prefer the summary endpoint for headline figures, and the full datasets for time series — don't scrape the docs pages for numbers when a JSON endpoint exists.
2. Use min.json for smaller/faster downloads where the docs offer it; use the unminified .json or .csv when you want it human-readable.
3. Read and display the last_update / includes_until date next to every figure (see §3.4).
4. Distinguish reported from extrapolated — non-ext_ vs ext_ fields (§3.3).
5. For the West Bank, decide between verified.* and unverified/flash fields and label which you used (§2.4).
6. Pin your version (v2 vs v3) so a format change doesn't silently break your consumer (§5).
7. Never present a figure without its source attribution and the documented undercount caveat (§3).

The maintainers curate a public gallery of ~30+ projects built on the data on their Example Usage page (S9, fetched 2026-07-10), including a community Python example they link as https://github.com/ummahrican/palestine-api. That gallery — not this explainer — is the maintainers' canonical showcase of real-world consumers.

---

5. Versioning: what v2 vs v3 means (and why to pin it)

The site serves versioned endpoints so it can make breaking changes without silently altering existing consumers (S8, fetched 2026-07-10). Per the versioning guide and the search-indexed guidance from the same page (S8, fetched 2026-07-10):

• A "breaking change" is, verbatim, "renaming object fields on already published resources" or "changing the meaning, intent or expectation of an already published field or resource." These trigger a new version.
• A non-breaking change — "correcting or changing values for a previously reported field," or "adding new fields … so long as it doesn't cause significant impact to an existing API's use" — does not trigger a new version. Practical consequence: values can change under you within the same version; version-pinning protects you from field/format changes, not from value revisions.
• v2 → v3 format difference: v2 uses a paged, array-of-objects layout (and offers CSV/JSON); v3 uses a condensed array-of-arrays format where the first array names the fields and their order for the records that follow, which makes the JSON smaller and faster to download. For JSON, the docs recommend v3.
• The source field was removed in v3 for Killed-in-Gaza, after the Ministry stopped populating it following the sixth list update — so if you rely on per-record source, you must use v2 (§2.1).

Plain-language meaning: you can usually swap v3 ↔ v2 in a path to move between formats, but they are not identical (v2 has source; v3 is array-of-arrays). Choose one deliberately and pin it.

---

6. Licensing and attribution

License: the repository releases both software and data into the public domain under the Unlicense (S13, fetched 2026-07-10). The license text states, verbatim: "This is free and unencumbered software & data released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software & data … for any purpose, commercial or non-commercial, and by any means." It is provided "'AS IS', WITHOUT WARRANTY OF ANY KIND."

What that means in plain language: the Unlicense imposes no legal obligation to attribute. But — and this is the whole point of this explainer — the maintainers' own docs repeatedly ask that the data be presented with its source and its limitations (§3). Attribution and caveat-carrying are therefore an ethical and accuracy requirement, not a legal one. Recommended citation form (offered as a suggestion for the maintainers to standardize — see §7):

"Data: Palestine Datasets, Tech for Palestine (data.techforpalestine.org), [dataset name], as of [last_update date], accessed [your access date]. Figures are sourced from [Gaza Ministry of Health / Government Media Office / UN OCHA as applicable] and are a documented undercount per the maintainers' own notes."

This explainer does not restate any of their figures as our own primary claim. Where a number appears above, it is quoted as the value their page displayed on the access date, with the source attached, for the sole purpose of showing readers how to read the data.

---

7. How to contribute or reach the maintainers (and an open offer)

Reporting a problem (verbatim, S11, fetched 2026-07-10): "If you have an issue or noticed a problem with our site or its datasets, we'd prefer you log it as a Github issue" — at https://github.com/TechForPalestine/palestine-datasets/issues/new . General inquiries: datasets@techforpalestine.org. The maintainers note, verbatim (S11): "we are a volunteer group and cannot guarantee that your message will receive a response."

Contributing (S10, fetched 2026-07-10): the project uses a standard GitHub fork → change → Pull Request workflow. Documentation lives as Docusaurus/MDX under site/docs. Welcomed contributions explicitly include documentation as well as data corrections (name-translation fixes, additions, and non-translation detail corrections to the Killed-in-Gaza list) and general suggestions via GitHub issues or the #palestine-datasets Discord channel. Because docs contributions are explicitly welcomed and the workflow is a plain PR, this explainer is offered as exactly that: a draft PR / issue the maintainers can accept, edit, or decline.

Two open offers to the maintainers:

1. This explainer, as a docs PR — take it as-is, edit freely, or tell us the format you prefer.
2. Standardized reuse/credit language (a suggested citation string like the one in §6) if you would find it useful to publish one, so downstream consumers cite consistently.

---

8. Anything not confirmed this session (marked unknown, not guessed)

To keep this document honest, the following were not confirmed against a page fetched on 2026-07-10 and are recorded as unknown rather than filled in:

• Rate limits / throttling / terms-of-use for the API: a dedicated API-usage page at the guessed path /docs/api/ returned HTTP 404 on 2026-07-10; the /docs/examples/ page is a project gallery, not a technical API reference (S9, fetched 2026-07-10). No rate-limit, quota, or ToS page was located this session. Status: unknown — confirm with the maintainers before building anything that assumes limits or their absence.
• CDN / caching headers and recommended polling frequency: not documented on the pages fetched this session. The docs state files update "in the morning (eastern time)" (S3, S4, S7), which implies polling more than once or twice daily is unnecessary, but an explicit caching policy was not found. Status: unknown.
• Exact current record counts and figures: these change; this explainer deliberately does not enshrine them. Fetch the live endpoints (§2, §4) and cite them with your own access date.
• Whether a Discord invite is currently on the Contact page: the Contact page fetched on 2026-07-10 (S11) listed email + GitHub only and did not list a Discord channel, whereas the Contributing page (S10) references a #palestine-datasets Discord channel. The live invite link itself was not captured this session. Status: unknown — check the Contributing page / repo for the current invite.

---

Prepared as a docs contribution for the Palestine Datasets maintainers. All claims cited to sources fetched 2026-07-10. Public record only. No operational, legal, or financial guidance is given or implied. Corrections welcome — this is a draft.