TH docs update

[matamadio]

The TH documentation needs to be updated to reflect update changes.

We should also take the chance to:

• Refactor it using easier/better docs platform such as jupyterbook
• Move it from https://github.com/GFDRR/thinkhazardmethods to a "docs" folder within this repo

[matamadio]

Now documentation pushed as PR: #1007

[matamadio]

The API page might need to be updated.
@ronitjadhav could you check about previous website API instructions and let me know if anything changes in the new version?

[ronitjadhav]

Hi, I reviewed the previous API instructions and compared them with the current implementation. Below are the updates that appear necessary for the new version of the API documentation.

API Documentation Updates

1. Division Codes Reference

The division codes reference link should be updated to use the new dataset:

https://github.com/GFDRR/thinkhazardmethods/blob/master/source/download/ADM1_TH.csv

Older division code references are now outdated and may return incorrect or missing results.

---

2. Hazard Type Code Changes

Several hazard codes have changed. These should be updated in the API documentation to ensure requests work correctly.

Old Code	Old Name	New Code	New Name
VO	Volcano	VA	Volcano
CY	Cyclones	TC	Tropical Cyclone
UF	Urban Floods	PF	Pluvial Flood
DR	Drought	DG	Water Scarcity

API parameter descriptions and examples should reflect these updated hazard codes.

---

3. Update API Examples (Division Codes)

Since {division_code} values have been updated, the example requests in the documentation should also be revised.

Examples

Pakistan (ADM0)

http://thinkhazard.org/en/report/PAK.json

Afghanistan – Kandahar District (ADM2)

http://thinkhazard.org/en/report/AFG015.json

These examples return valid results using the current API structure.

[matamadio]

Thanks, could you provide an example for the urban areas as well? Is it still using the same query structure?

[ronitjadhav]

Yes, urban areas also use the same {division_code} parameter.

Examples (URB)

Paris (URB)
http://thinkhazard.org/en/report/2878.json

Berlin (URB)
http://thinkhazard.org/en/report/548.json

[matamadio]

Ok, thanks. I'm building a query builder page to facilitate access. Will update on the same PR soon.

[matamadio]

New documentation is online: https://gfdrr.github.io/thinkhazard

Please @stufraser1 @pzwsk have a look, it is mostly fine though today I'll be fixing a few details:

• light (white) theme as default for better readability Include dark-mode images
• Couple fixes on the flood approach content
• Fix link to json files (ADM, urban boundaries)
• API builder works decently but will need a few fixes
  • the generated API maybe not matching with data until moving scores from int to production
  • fix html generation (absolute https://gfdrr.github.io/thinkhazard/build/query_builder.html instead of https://gfdrr.github.io/thinkhazard/build/query_builder-8920da0083e42ece200960e72dca373b.html

[matamadio]

@pzwsk I just updated the TH docs homepage to include a disclaimer on TH score interpretetation:

Important: Hazard vs. Risk

**ThinkHazard! provides hazard information, not risk assessments.** It is essential to understand the distinction between these concepts:

- **Hazard** (as defined by UNDRR): "A process, phenomenon or human activity that may cause loss of life, injury or other health impacts, property damage, social and economic disruption or environmental degradation."

- **Risk** (as defined by UNDRR): "The potential loss of life, injury, or destroyed or damaged assets which could occur to a system, society or a community in a specific period of time, determined probabilistically as a function of hazard, exposure, vulnerability and capacity."

ThinkHazard! classifies the probability and intensity of natural hazards at specific locations. However, **hazard levels do not directly translate to risk levels**. A comprehensive risk evaluation must additionally account for:

- **Exposure**: The presence of people, assets, infrastructure, and economic activities in hazard-prone areas
- **Vulnerability**: The susceptibility of exposed elements to damage or harm from hazardous events

For example, an area with high flood hazard but minimal population or assets would not necessarily represent high risk. Conversely, areas with moderate hazard levels may face significant risk if highly vulnerable populations or critical infrastructure are exposed.

Users should consider ThinkHazard! classifications as a foundational input for risk-informed decision-making, supplemented with local exposure and vulnerability assessments for comprehensive disaster risk management.