ICT for Civic Data — Turin University 2025-26
# From Data
to Map
Crash Course — Day 2 Afternoon
civicliteraci.es
--- # Define Your Angle Note: "This morning we discussed how to go from a concrete example to a broader argument. Now it's time to commit: what is YOUR angle?" --- ## Write down your angle Based on this morning's discussion, define your proposal angle: 1. What **territory**? (be specific: a country, a region, a coastline) 2. What **issue**? (flood risk, drought, wildfire, cyclone exposure) 3. What **population or infrastructure** is affected? 4. In one sentence, what would your proposal **argue**? Write this down. You will use it for the rest of the week. Note: Individual work, 10 minutes. Circulate and push for precision. "Southeast Asia" is too broad. "Coastal communities in the Mekong Delta" is specific enough. The one-sentence argument is the hardest part; help students who are stuck. --- # Data Formats
and Sources Note: "Before you start searching, a quick overview of what you will encounter." --- ## Where data lives | Location | What you find | How to get it | |---|---|---| | **Open data portal** | Downloadable files (CSV, Excel, GeoJSON) | Browse and download | | **API** | Structured data you can query | Send a request, get a response | | **Web page** | Tables, lists, text | Scraping (manual or AI-assisted) | | **PDF or report** | Tables, figures, text | Extraction (AI, Tabula, OCR) | Your AI tool can help with all of these. But you need to know **what you are looking at**. Note: Quick theory recap from the lectures. The point is not to re-teach; it is to name the categories so students know what to expect when they start searching. --- ## Common data formats | Format | What it is | Good for | |---|---|---| | **CSV** | Text file with commas separating values | Tabular data. Opens in any spreadsheet. | | **GeoJSON** | JSON with coordinates | Map data. Goes straight onto Leaflet. | | **Shapefile** | Legacy GIS format (3-6 files together) | Geographic boundaries. Needs conversion for web maps. | | **JSON** | Nested, structured data | API responses. Needs flattening for tables. | | **Excel (.xlsx)** | Spreadsheet with sheets and formulas | Common in government data. May need cleaning. | If you are unsure about a format, ask your AI tool: "I downloaded a .shp file. What is it and how do I use it on a Leaflet map?" Note: Students will encounter all of these during their search. The key message: you don't need to memorise this, but you need to know that formats differ and that your AI tool can help you convert between them. --- ## What is an API? An **API** (Application Programming Interface) is a way to ask a database for specific data. Instead of downloading a huge file and filtering it yourself, you send a **request** and get back only what you asked for. **Example:** the REST Countries API ``` https://restcountries.com/v3.1/name/kenya ``` This returns data about Kenya: population, area, region, capital, coordinates. APIs are useful because your AI tool can **write the request for you** and **process the response**. Note: Brief. Some students have seen this in Lecture 2. For others it's new. The REST Countries example is concrete and testable. The key point: an API is just a URL that returns data instead of a web page. --- # Finding Data
for Your Angle Note: "You have an angle. You know about data formats and sources. Now find data that would strengthen your proposal." --- ## Two habits before you search **1. Be precise.** The more specific your question to Gemini, the better the answer.
Vague
"Find me some data about disasters."
Precise
"I need geospatial data on flood events in the Mekong Delta region of Vietnam, with coordinates, dates, and severity. What open sources exist?"
**2. Tell Gemini you are a beginner.** It will adapt its language and explain technical choices instead of assuming you know. Note: These two habits make a big difference. Students who ask vague questions get vague answers and then don't know what to do with them. Students who are precise get actionable responses. --- ## Look at the data before going further When you find a source: **download a sample and look at it** before asking Gemini to do anything with it. - How many rows? How many columns? - What do the column names mean? - Are there coordinates? In what format? - Is it the right geographic area? The right time period? If you skip this, you will ask Gemini imprecise questions and get surprising results. Note: Reinforce the habit from this morning's shared exercise. Looking at the data first is what makes the difference between a productive AI interaction and a frustrating one. --- ## Working efficiently with AI tools - Use **web chat** (Gemini web, ChatGPT) for discovery and simple questions. Free, no tokens. - Use **CLI** (Gemini CLI, Claude Code) for working with files, building maps, running scripts. Costs tokens. - **Split complex tasks** into smaller steps. One prompt per step. - **Resume sessions**: use `gemini --resume` to reopen your latest session. Use separate tabs for separate tasks. The CLI is powerful but expensive. Do your thinking in web chat, do your building in the CLI. Note: Practical tip from today's experience. Students were burning tokens on simple discovery questions that web chat handles for free. The rule of thumb: if you're asking a question, use web chat. If you need the AI to touch your files, use the CLI. --- ## Git branches and GitHub Pages When you ask the agent to publish to GitHub Pages, it may try to create a **gh-pages branch** instead of using **main**. **What is a branch?** A parallel version of your repository. The agent creates one because many tutorials use a separate branch for published content. **Your options:** - Tell the agent: "publish on the main branch, not gh-pages" - Or: go to Settings → Pages and change the source to the gh-pages branch Either works. Just be consistent. Note: This comes up frequently. Students see an error or a blank page because Pages is set to main but the agent pushed to gh-pages. Explain branches briefly: like a copy of your project that exists alongside the original. They don't need to understand git branching deeply, just enough to fix this specific problem. --- ## Common issues with agentic tools **The agent thinks too long.** If nothing happens for 5-10 minutes, press **Escape** to stop it. You may need to press Escape multiple times. Then rephrase your request more simply. **The agent over-engineers.** Ask for a "simple Leaflet map that can be published on GitHub Pages." Without "simple," the agent will build something complex and waste your tokens. **Browser cache.** After pushing changes, your GitHub Pages URL may show the old version. The agent may ask you to **hard refresh** (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac). This is safe: it just clears the cached version. **The agent fails at simple tasks.** Sometimes the agent cannot download a file that is one click away. If that happens, download it yourself and drag-and-drop it into your Codespace file explorer. Not everything needs to go through the agent. Note: These are the four most common frustrations. Addressing them upfront saves a lot of time during the exercise. The "simple" keyword is especially important: without it, Gemini will create React apps or multi-file projects when a single HTML file would do. --- ## The process: Find, then Get, then Verify Do them **separately**: 1. **Find**: ask Gemini what sources exist. Save the list to `sources.md` in your repo. 2. **Get**: pick one source. Ask Gemini to write a script that downloads it. Read the script. Run it. 3. **Verify**: add the data to your map. Does it look right? If step 3 reveals a problem, go back to step 1 or 2. Note: Same discipline as this morning, now applied to their own angle. Emphasise: the sources.md file is documentation. It is part of their proposal's methodology. --- ## Exercise: find, get, and map data for your angle **Individual work — rest of the afternoon and tomorrow morning** 1. **Define** your angle (from earlier) 2. **Find** data sources relevant to your argument. Document them in `sources.md`. 3. **Get** one dataset. Use a script. 4. **Verify** by adding it as a layer on your map. 5. **Push** and check the live page. If you finish one dataset, find and add another. This exercise continues tomorrow morning. Note: Main working block. Circulate and help. This is the start of the individual work, not the end. Students will continue tomorrow morning. Common patterns: students who can't find data for their exact angle (help them broaden the search or adjust the angle). Students who find data but can't get it onto the map (help with format conversion). Students who skip Find and go straight to asking Gemini to "make a map of X" (stop them, ask them to separate the steps). --- # Wrap-Up Note: Bring everyone back. --- ## Where are you? Quick round — share where you are in the process: - Have you **defined** your angle? - Have you **found** relevant data sources? - Have you started **getting** data? - Have you managed to **add a layer** to your map? No pressure to be finished. We continue this tomorrow morning. Note: This is a check-in, not a presentation. Just go around the room and get a sense of where people are. Some will have a layer on their map. Others will still be searching. Both are fine. The goal is to know who needs help tomorrow morning. --- ## What we covered today - Practiced Find → Get → Verify with a shared dataset - Understood why precise prompts matter (beginner vs. expert assistant) - Connected concrete examples to broader proposal arguments - Defined individual angles - Started finding and mapping data for our own proposals **Tomorrow morning:** continue the individual work, then we move to verification and cleaning. Note: Connect morning (shared, guided) to afternoon (individual, self-directed). Tomorrow morning is continuation time, then the focus shifts to data quality. --- # Questions?