Web Mapping

What actually happens

You open a web map centred on Nairobi. In the second before it appears, this happens:

1. The browser requests an HTML page. That page loads the Leaflet CSS and JavaScript.
2. Leaflet creates a <div> and works out which geographic area it must cover at the requested zoom.
3. It calculates which tiles — small fixed square images, conventionally 256 × 256 pixels — cover that area, typically nine to twenty of them.
4. It issues one HTTP request per tile, in parallel, to a tile server.
5. Each tile arrives as a PNG and is positioned absolutely inside the div by CSS.
6. Your own data — points, boundaries — arrives separately as GeoJSON and is drawn as SVG or canvas on top.

The whole design rests on one decision: pre-render the base map once, into fixed tiles, and serve them as static images. Nothing is computed per user. A tile is just a file, so it caches in the browser, in the CDN, and at every proxy in between. This is why a web map can serve millions of users on modest infrastructure, and it is why the "slippy map" replaced the older approach of asking a server to render a fresh image for every pan.

The tile pyramid

A tile is addressed by three numbers: z (zoom), x (column, west to east) and y (row, north to south — the origin is the top-left corner, which surprises people used to y increasing northward). A tile URL is a template with those three slots:

https://tile.openstreetmap.org/{z}/{x}/{y}.png

The conversion from longitude and latitude to tile indices is:

Web Mercator, and where it lies

Almost every web map uses EPSG:3857, "Web Mercator". It was chosen for one practical reason: Mercator is conformal, so shapes and angles are locally correct and north is always up, which makes tiles that stitch seamlessly and pan intuitively. The price is area. Mercator inflates area by a factor of sec²φ — that is, 1/cos²(latitude).

This is the source of the familiar Greenland problem. Greenland's true area is about 2.17 million km²; the Democratic Republic of the Congo's is about 2.34 million km². The DRC is genuinely the larger country. On a Web Mercator map Greenland appears roughly fourteen times bigger.

There is a local point worth noticing here. Kenya sits on the equator, so Web Mercator distortion across Kenya is negligible — at 1.3° the inflation factor is 1.0005, five parts in ten thousand. For a map of Nairobi County you may reason about Web Mercator areas without much guilt. For a map of Africa, or of the world, you may not. Knowing which situation you are in is the professional skill; assuming one or the other is how errors happen.

Three ways to get data onto the map

The failure mode you will meet is loading a national dataset as a single GeoJSON, discovering it is 40 MB, and watching the browser freeze. The fix is not to optimise the GeoJSON; it is to recognise that you have chosen the wrong delivery mechanism. Week 9 covers the right one.

Standards, and why they exist

The Open Geospatial Consortium publishes the specifications that let software from different vendors interoperate. WMS returns a rendered image; WFS returns actual features; WMTS returns tiles. All are covered in week 7. Their value is concrete: a county publishing a WMS endpoint can be consumed in QGIS, ArcGIS, Leaflet and OpenLayers with no bespoke work by anyone. Standards are what stop every dataset needing its own client.

Reading. The OpenStreetMap wiki article "Slippy map tilenames" — the authoritative statement of the tile maths, with reference implementations. Peterson, Mapping in the Cloud, ch. 1–3. The OGC's own overview of its standards baseline.

JavaScript for people who know Python

The syntax is learnable in an afternoon. What causes trouble is the handful of places where JavaScript behaves differently from what your Python instincts predict.

The last row is the one that matters, and it is not a syntax difference — it is a difference in how the language runs. Python executes a line, waits for it to finish, moves on. JavaScript in the browser must never wait, because waiting would freeze the page. So an operation that takes time — fetching a file over the network — returns immediately with a promise of a future result, and your code says what to do when it arrives.

// WRONG — data is undefined, because fetch has not finished
let data;
fetch("facilities.geojson").then(r => r.json()).then(d => { data = d; });
console.log(data.features.length);          // TypeError

// RIGHT — do the work inside the handler
fetch("facilities.geojson")
  .then(r => {
    if (!r.ok) throw new Error(`HTTP ${r.status}`);   // fetch does NOT throw on 404
    return r.json();
  })
  .then(data => { console.log(data.features.length); })
  .catch(err => console.error("failed to load:", err));

// RIGHT — the same thing, more readable
async function load() {
  const r = await fetch("facilities.geojson");
  if (!r.ok) throw new Error(`HTTP ${r.status}`);
  const data = await r.json();
  console.log(data.features.length);
}

HTTP, in the amount you need

Every piece of data on your map arrives through an HTTP request. Four things to know:

• Methods. GET retrieves and must not change anything. POST creates. PUT replaces, PATCH modifies, DELETE removes. Week 8 uses all of them.
• Status codes. 200 fine; 301/302 moved; 400 your request was malformed; 401 not authenticated; 403 authenticated but not allowed; 404 not found; 500 the server broke. The distinction between 401 and 403, and between 400 and 500, tells you which side of the wire to debug.
• Headers. Metadata on both sides. Content-Type says what the body is; the CORS headers decide whether your JavaScript is allowed to read the response.
• CORS. By default, JavaScript on your page may not read a response from a different origin. The server must opt in with an Access-Control-Allow-Origin header. You will meet this in week 7 with GeoServer, and it is the most common cause of a map that works locally and fails when deployed.

GeoJSON, properly

GeoJSON (RFC 7946) is the interchange format of the web mapping world. It is JSON with a specified structure.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [36.8219, -1.2921]        // [longitude, latitude] — in that order
      },
      "properties": {
        "name": "Kenyatta National Hospital",
        "level": 6,
        "beds": 1800
      }
    }
  ]
}

Seven rules that the specification actually imposes, and that people actually break:

1. Coordinates are [longitude, latitude]. X before Y. This is the opposite of how you say it aloud and the opposite of Leaflet's own L.latLng.
2. The CRS is always WGS84 (CRS84, equivalent to EPSG:4326). RFC 7946 removed the ability to declare any other. If your data is in UTM, transform it before writing GeoJSON — a file with UTM coordinates in it is not GeoJSON, whatever the extension says.
3. Seven geometry types: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, GeometryCollection.
4. Polygon rings must close — the last coordinate pair repeats the first.
5. Ring winding order: exterior rings counter-clockwise, interior rings (holes) clockwise, by the right-hand rule.
6. No comments, no trailing commas, no NaN. It is JSON, and JSON has none of these.
7. A geometry may be null — a valid Feature with attributes and no location.

Reading. RFC 7946, the GeoJSON specification — short, readable, and worth reading in full. MDN's "JavaScript first steps" and "Using Fetch". Eloquent JavaScript ch. 1–5 (free online) if you need the language properly rather than quickly.

The smallest working map

Leaflet needs three things: a CSS file, a JavaScript file, and a <div> that has a height. The third catches everyone.

<link rel="stylesheet"
      href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

<style>
  html, body { height: 100%; margin: 0; }
  #map { height: 100%; }        /* without a height, the map is invisible */
</style>

<div id="map"></div>

<script>
  // note the order: LATITUDE first in Leaflet
  const map = L.map("map").setView([-1.0996, 37.0134], 15);   // JKUAT main campus

  L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png", {
    maxZoom: 19,
    attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
  }).addTo(map);
</script>

Attribution is not optional

OpenStreetMap data is licensed under the ODbL, which requires attribution — the credit line in the corner is a licence condition, not decoration. Removing it is a licence breach. Some tile providers additionally cap usage: OSM's own tile servers are for development and low-volume use only, and a deployed application sending them significant traffic will be blocked. For anything real, use a provider with terms you have read — Carto, Stadia, MapTiler, or your own tile server. This comes up in week 10.

Markers, popups and tooltips

A marker is a point with an icon. A popup opens on click and holds arbitrary HTML. A tooltip appears on hover and should be short. The default marker icon is a blue pin; a custom icon needs its size and, critically, its anchor — the pixel within the image that sits on the geographic point. Get the anchor wrong and every marker is offset by half an icon, which looks fine on its own and is wrong everywhere.

const clinicIcon = L.icon({
  iconUrl:     "icons/clinic.png",
  iconSize:    [32, 32],
  iconAnchor:  [16, 32],    // bottom centre — the tip of the pin
  popupAnchor: [0, -32]     // popup opens above the icon, not over it
});

L.marker([-1.0996, 37.0134], { icon: clinicIcon })
  .addTo(map)
  .bindPopup("<strong>JKUAT Health Centre</strong><br>Level 3 · Open 24 h")
  .bindTooltip("JKUAT Health Centre");

GeoJSON layers — where the real work happens

L.geoJSON() takes a FeatureCollection and turns it into a layer. It also handles the coordinate-order swap for you. Four options carry almost all of its power:

• pointToLayer(feature, latlng) — decides what a Point becomes. Return an L.circleMarker instead of a pin and you can size and colour it by an attribute.
• style(feature) — returns a style object for lines and polygons. Called once per feature, so it can depend on the data.
• onEachFeature(feature, layer) — runs once per feature after creation. Bind popups and event handlers here.
• filter(feature) — return false to drop a feature before it is drawn.

const res = await fetch("facilities.geojson");
const data = await res.json();

const layer = L.geoJSON(data, {

  filter: f => f.properties.operational === true,

  pointToLayer: (f, latlng) => L.circleMarker(latlng, {
    radius: Math.sqrt(f.properties.beds) / 2,   // area ∝ beds, not radius ∝ beds
    fillColor: "#0E6E78",
    color: "#ffffff",
    weight: 1,
    fillOpacity: 0.75
  }),

  onEachFeature: (f, lyr) => {
    const p = f.properties;
    lyr.bindPopup(`<strong>${p.name}</strong><br>Level ${p.level} · ${p.beds} beds`);
    lyr.on("mouseover", e => e.target.setStyle({ weight: 3 }));
    lyr.on("mouseout",  e => e.target.setStyle({ weight: 1 }));
  }

}).addTo(map);

map.fitBounds(layer.getBounds(), { padding: [20, 20] });   // let the data set the view

Two details in that code are worth dwelling on. fitBounds lets the data decide the view rather than a hard-coded setView — so the map still works when the dataset changes. And the radius uses a square root: human perception reads circle area, so scaling the radius directly by the value makes a facility with four times the beds look sixteen times bigger. Getting this wrong is one of the most common quantitative errors in thematic mapping.

Reading. The Leaflet quick-start guide and the "Using GeoJSON with Leaflet" tutorial — this week's primary text. The full API reference, skimmed once so you know what exists.

Counts are almost always the wrong variable

Start here, because it is the error that invalidates whole maps. A choropleth colours areas by a value. If that value is a raw count, the map shows you where the people are, not where the phenomenon is. A map of the absolute number of health facilities per county is, to a first approximation, a map of county population — and it will be read as a map of health provision, which is a different and false claim.

Normalise: facilities per 100,000 people, cases per 1,000, hectares per km². The choropleth is a map of intensity, and intensity requires a denominator. There is exactly one exception — mapping a total that genuinely is the quantity of interest, such as total budget allocated — and even then a proportional symbol is usually the better form.

Classification changes the message

Having chosen a variable, you must choose how to cut it into classes. This is not a technical detail; it determines what the reader concludes.

Manual is underrated. If the WHO guideline is 1.5 mg/L, put a class break at 1.5. A statistically optimal break at 1.43 tells the reader nothing; the guideline tells them everything.

Colour

• Sequential — light to dark in one hue, for ordered data from low to high.
• Diverging — two hues meeting at a neutral midpoint, for data with a meaningful centre: change from a baseline, above and below a target.
• Qualitative — distinct hues of similar lightness, for categories with no order. Land cover, ownership type. Never use a sequential ramp for categories; it implies an ordering that does not exist.

Use ColorBrewer rather than choosing colours by eye — the schemes are perceptually ordered and tested. Around 8% of men have a red–green colour vision deficiency, so a red-to-green diverging scheme is unreadable to roughly one in twelve of your male users; use ColorBrewer's colourblind-safe schemes, such as brown–blue-green or purple–green. And check your map in greyscale: if the classes are still distinguishable, lightness is doing the work and the map will survive both photocopying and colour blindness.

Five to seven classes is the practical maximum. Beyond that readers cannot match a polygon to a legend swatch reliably, and the extra precision is illusory.

// Manual breaks — chosen, documented, defensible
const BREAKS = [0, 10, 15, 20, 25];
const COLORS = ["#edf8fb", "#b2e2e2", "#66c2a4", "#2ca25f", "#006d2c"];

function colorFor(rate) {
  if (rate == null) return "#cccccc";        // no data ≠ zero — show it differently
  for (let i = BREAKS.length - 1; i >= 0; i--) {
    if (rate >= BREAKS[i]) return COLORS[i];
  }
}

L.geoJSON(counties, {
  style: f => ({
    fillColor: colorFor(f.properties.fac_per_100k),
    weight: 1, color: "#ffffff", fillOpacity: 0.85
  })
}).addTo(map);

// --- legend, built from the same arrays so it can never disagree ------
const legend = L.control({ position: "bottomright" });
legend.onAdd = () => {
  const div = L.DomUtil.create("div", "legend");
  div.innerHTML = "<h4>Facilities per 100,000</h4>";
  BREAKS.forEach((b, i) => {
    const hi = BREAKS[i + 1];
    div.innerHTML += `<i style="background:${COLORS[i]}"></i> ${b}${hi ? "–" + hi : "+"}<br>`;
  });
  return div;
};
legend.addTo(map);

Accessibility, briefly and seriously

A map built only for a mouse excludes people who navigate by keyboard, and a map whose only information channel is colour excludes people who cannot distinguish those colours. Three things cost you almost nothing:

• Ensure everything reachable by click is reachable by Tab and activated by Enter. Leaflet gives markers keyboard focus by default — do not remove it.
• Never carry information in colour alone. Add a pattern, a label, or a value in the popup.
• Provide the underlying data as a table or a download. It is the most robust accessibility feature a map can have, and it also serves the person who wants to check your numbers.

Reading. Muehlenhaus, Web Cartography, ch. 4–6. Brewer, Designing Better Maps, on classification and colour. The ColorBrewer 2.0 tool. Monmonier, How to Lie with Maps, ch. 3 — short, and it will change how you read every choropleth you see afterwards.

Why not just serve files?

You have been loading GeoJSON files. For a static map of a few hundred features that is entirely correct. It stops working when any of the following becomes true, and in a real application all of them do:

• The data changes, and several people change it — a file has no concurrency control, and two simultaneous writers lose each other's work.
• You need a subset. Serving a 40 MB file so the browser can discard 39 MB of it is indefensible on a mobile connection.
• You need a computed answer — facilities within 5 km of this point, the county containing this click. That is a query, not a file read.
• You need transactions, backups, permissions, or an audit trail.

PostGIS extends PostgreSQL with spatial types, several hundred spatial functions, and spatial indexing. It is the standard open-source spatial database and the back end of a large share of the world's public-sector GIS.

Getting data in

createdb webmap
psql -d webmap -c "CREATE EXTENSION postgis;"

# load a shapefile, reprojecting to WGS84 on the way in
ogr2ogr -f "PostgreSQL" PG:"dbname=webmap user=postgres" counties.shp \
  -nln counties -nlt PROMOTE_TO_MULTI \
  -t_srs EPSG:4326 -lco GEOMETRY_NAME=geom -lco FID=id

# load a CSV of points
ogr2ogr -f "PostgreSQL" PG:"dbname=webmap user=postgres" facilities.csv \
  -nln facilities -oo X_POSSIBLE_NAMES=lon -oo Y_POSSIBLE_NAMES=lat \
  -a_srs EPSG:4326 -lco GEOMETRY_NAME=geom

Note -t_srs (transform to) against -a_srs (assign, without transforming). Use -a_srs only when the data is already in that CRS but is not labelled. Using it when the data is in a different CRS silently mislabels everything, and nothing will tell you.

geometry or geography?

The practical pattern: store as geometry with SRID 4326 because that is what the web wants, and either cast to geography or transform to UTM whenever you measure.

-- WRONG: geometry is in EPSG:4326, so this is SQUARE DEGREES
SELECT name, ST_Area(geom) FROM counties WHERE name = 'Nairobi';
--  Nairobi | 0.0565          ← a number, with no meaning

-- RIGHT: project to UTM 37S, divide to km²
SELECT name, ST_Area(ST_Transform(geom, 32737)) / 1e6 FROM counties
WHERE name = 'Nairobi';
--  Nairobi | 696.1           ← km²

-- ALSO RIGHT: cast to geography, which always works in metres
SELECT name, ST_Area(geom::geography) / 1e6 FROM counties
WHERE name = 'Nairobi';
--  Nairobi | 696.0

The core function set

Indexes, and the difference they make

Without an index, a spatial query compares your search geometry against every row in the table. A GiST index stores each geometry's bounding box in a tree, so the database can eliminate most rows before doing any real geometric work.

CREATE INDEX facilities_geom_idx ON facilities USING GIST (geom);
ANALYZE facilities;                -- update the planner's statistics

-- prove it worked: run this before and after creating the index
EXPLAIN ANALYZE
SELECT f.name
FROM facilities f JOIN counties c ON ST_Intersects(f.geom, c.geom)
WHERE c.name = 'Kiambu';
-- before: Seq Scan on facilities
-- after:  Index Scan using facilities_geom_idx

Reading. Obe & Hsu, PostGIS in Action, 3rd ed., ch. 1–5. The PostGIS manual's function reference — learn to navigate it; it is the text you will still be using in ten years. The Crunchy Data "Introduction to PostGIS" workshop is free and excellent.

The architecture you are building

GeoJSON straight from SQL

PostGIS can assemble a complete FeatureCollection in the database, so your API becomes a thin pipe rather than a place where objects are laboriously rebuilt in Python.

SELECT json_build_object(
  'type',     'FeatureCollection',
  'features', COALESCE(json_agg(feature), '[]'::json)   -- [] not null when empty
)
FROM (
  SELECT json_build_object(
    'type',       'Feature',
    'geometry',   ST_AsGeoJSON(geom)::json,
    'properties', json_build_object('id', id, 'name', name, 'beds', beds)
  ) AS feature
  FROM facilities
  WHERE geom && ST_MakeEnvelope(%s, %s, %s, %s, 4326)   -- bbox, index-aware
  LIMIT 5000
) f;

Two things there earn their place. COALESCE(..., '[]') means an empty result is a valid empty FeatureCollection rather than null, which would crash your JavaScript. And the && bounding-box operator uses the GiST index, so a request for the current map view touches only the rows in view — which is what makes the whole approach scale.

A minimal API

from flask import Flask, jsonify, request, abort
import psycopg2, psycopg2.extras

app = Flask(__name__)

@app.route("/api/facilities")
def facilities():
    try:
        bbox = [float(v) for v in request.args["bbox"].split(",")]
        assert len(bbox) == 4
    except (KeyError, ValueError, AssertionError):
        abort(400, "bbox required as minx,miny,maxx,maxy")

    with psycopg2.connect(DSN) as conn, conn.cursor() as cur:
        cur.execute(SQL, bbox)          # parameterised — NEVER f-string user input
        return jsonify(cur.fetchone()[0])

let layer = L.geoJSON(null).addTo(map);

async function refresh() {
  const b = map.getBounds();
  const bbox = [b.getWest(), b.getSouth(), b.getEast(), b.getNorth()].join(",");
  const r = await fetch(`/api/facilities?bbox=${bbox}`);
  if (!r.ok) return console.error("API error", r.status);
  layer.clearLayers().addData(await r.json());
}

map.on("moveend", refresh);   // moveend, not move — one request per pan, not hundreds
refresh();

Binding to moveend rather than move is the difference between one request per pan and several hundred. On a laboratory network you might not notice; on a phone you will.

Keeping payloads small

• Select only the columns the map uses. A table has thirty attributes; the popup shows four. Sending thirty is thirty.
• Filter by bounding box. Always.
• Simplify by zoom. ST_Simplify with a tolerance scaled to the zoom level: national boundaries at zoom 6 do not need centimetre vertices. Use ST_SimplifyPreserveTopology for polygons, or adjacent counties will develop gaps between them.
• Reduce coordinate precision. ST_AsGeoJSON(geom, 5) gives about one metre — plenty for a web map, and it can cut file size by a third against the fifteen decimal places PostGIS emits by default.
• Cap the result. A LIMIT with an honest message beats a request that times out.

Reading. Obe & Hsu, ch. 9 on PostGIS output functions. The Flask quickstart. Crunchy Data's writing on serving GeoJSON and vector tiles directly from PostgreSQL.

What GeoServer is for

Last week you wrote your own API. It works, and for a bespoke application it is often the right choice. But it is yours — nobody else's software knows how to talk to it. GeoServer instead speaks the OGC standards, which means that the moment you publish a layer, it can be consumed by QGIS, ArcGIS, OpenLayers, Leaflet and a dozen other clients with no further work by anyone. That interoperability is the entire value proposition, and it is why national mapping agencies and county governments run GeoServer rather than bespoke APIs.

The object model

• Workspace — a namespace grouping related layers, e.g. kiambu.
• Store — a connection to a data source: your PostGIS database, a directory of GeoTIFFs.
• Layer — one publishable table or coverage from a store.
• Layer group — several layers served as one, in a fixed draw order.
• Style — an SLD document describing how a layer is drawn.

Three services, three jobs

The decision is nearly always: does the browser need the geometry? If it only needs to look at it, WMS or WMTS — the server does the drawing and sends pixels, and a million-feature layer costs the same as a hundred-feature one. If the user must click a feature and get its attributes, or you want to restyle without a server round trip, WFS or your own GeoJSON API.

GetCapabilities

Every OGC service answers a GetCapabilities request with an XML document listing what it offers: layer names, titles, supported coordinate systems, bounding boxes, available formats, and the operations it supports. It is a machine-readable contract, and it is how QGIS populates its layer list when you paste in a WMS URL.

# what does this server offer?
http://localhost:8080/geoserver/wms?service=WMS&version=1.3.0&request=GetCapabilities

# a rendered image
http://localhost:8080/geoserver/kiambu/wms?service=WMS&version=1.3.0
  &request=GetMap&layers=kiambu:facilities&styles=
  &bbox=36.6,-1.3,37.2,-0.9&width=768&height=512&crs=EPSG:4326&format=image/png

# the features themselves, as GeoJSON
http://localhost:8080/geoserver/kiambu/wfs?service=WFS&version=2.0.0
  &request=GetFeature&typeName=kiambu:facilities&outputFormat=application/json
  &count=100

Learning to read these URLs is worth an hour. When a layer fails to appear in Leaflet, constructing the equivalent GetMap request by hand and pasting it into the address bar tells you immediately whether the problem is GeoServer or your client code.

L.tileLayer.wms("http://localhost:8080/geoserver/kiambu/wms", {
  layers: "kiambu:facilities",
  format: "image/png",
  transparent: true,          // without this you get an opaque white rectangle
  version: "1.3.0",
  attribution: "Kiambu County"
}).addTo(map);

SLD in one page

Styled Layer Descriptor is the OGC's XML styling language. It is verbose, and it is also a genuine standard that transfers between servers. The structure is a set of rules, each with an optional filter and one or more symbolizers.

<Rule>
  <Name>Level 4 and above</Name>
  <ogc:Filter>
    <ogc:PropertyIsGreaterThanOrEqualTo>
      <ogc:PropertyName>level</ogc:PropertyName>
      <ogc:Literal>4</ogc:Literal>
    </ogc:PropertyIsGreaterThanOrEqualTo>
  </ogc:Filter>
  <PointSymbolizer>
    <Graphic>
      <Mark>
        <WellKnownName>circle</WellKnownName>
        <Fill><CssParameter name="fill">#0E6E78</CssParameter></Fill>
      </Mark>
      <Size>12</Size>
    </Graphic>
  </PointSymbolizer>
</Rule>

Rules can also carry MinScaleDenominator and MaxScaleDenominator, which is how a layer shows only labels at small scales and full symbology at large ones. Writing SLD by hand is tedious; generate a first version by styling the layer in QGIS and exporting as SLD, then edit. That is standard professional practice, not a shortcut.

Caching

GeoServer bundles GeoWebCache, which stores rendered tiles so that repeat requests are served as files rather than re-rendered. For any layer that changes less often than it is viewed — which is nearly all base data — this is the difference between a map that feels instant and one that does not. Seed the cache for the zoom levels you actually serve, and remember to invalidate it when the underlying data changes, because a stale tile cache is a genuinely confusing bug: the database is right and the map is wrong.

Reading. The GeoServer user manual, sections on data, styling and security. The OGC WMS 1.3.0 and WFS 2.0 specifications — skim the operations, do not read cover to cover. The GeoServer SLD cookbook, which is the fastest route to working styles.

From reading to writing

Everything so far has been read-only. The moment users can write, three new problems appear that did not exist before: validation (is this input sane?), authorisation (may this person do this?) and integrity (what happens if two people edit the same feature?). These are what separate an application from a demo.

Map HTTP methods onto operations conventionally, because clients and proxies rely on the conventions — in particular that GET never changes anything, which is why a crawler must never be able to delete your data by following a link:

Drawing on the map

Leaflet.draw and Leaflet-Geoman both add drawing and editing controls. The workflow is the same: the user draws, you receive a layer, you convert it to GeoJSON, you post it with the form data.

const drawn = new L.FeatureGroup().addTo(map);

map.addControl(new L.Control.Draw({
  edit: { featureGroup: drawn },
  draw: { polygon: true, marker: true, polyline: false,
          circle: false, rectangle: false, circlemarker: false }
}));

map.on(L.Draw.Event.CREATED, e => {
  drawn.clearLayers().addLayer(e.layer);       // one feature at a time
  document.querySelector("#report-form").hidden = false;
});

async function submit(ev) {
  ev.preventDefault();
  const layers = drawn.getLayers();
  if (!layers.length) return showError("Draw the location on the map first.");

  const res = await fetch("/api/reports", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      geometry:    layers[0].toGeoJSON().geometry,
      category:    form.category.value,
      description: form.description.value
    })
  });

  if (res.status === 201) { drawn.clearLayers(); refresh(); showOk("Report saved."); }
  else showError((await res.json()).error ?? "Could not save the report.");
}

Validate twice

Client-side validation is for the user: fast feedback, no wasted round trip. Server-side validation is for correctness, because anything a browser can send, an attacker can send without using a browser. Disabling a submit button prevents nothing — curl does not run your JavaScript. Every rule that must hold has to be enforced on the server; the client copy is a convenience.

For spatial data specifically, check: the geometry is the type you expected; it is valid (ST_IsValid); it falls inside your area of interest; polygons are not absurdly large or self-intersecting; and the vertex count is bounded, or someone will post a polygon with a million points.

# CATASTROPHIC — the user controls your SQL
cur.execute(f"SELECT * FROM reports WHERE category = '{cat}'")

# A category of:  x' OR '1'='1
#   returns every row, including rows the user should never see.

# CORRECT — the driver sends the value separately from the statement
cur.execute("SELECT * FROM reports WHERE category = %s", (cat,))

Secrets

Anything in your JavaScript is public. Not "hard to find" — public: it is delivered to every visitor and readable with two clicks. Database passwords, API keys with billing attached, and admin tokens must live in server-side environment variables, never in client code and never committed to git.

Where a third-party key must be used from the browser — some tile providers require this — restrict it at the provider: lock it to your domain, cap the request rate, and set a spending limit. Treat a leaked key as a bill you will personally receive, because that is how it usually presents.

Authentication, in the amount this unit needs

You are not building a production identity system. You do need to understand the shape: authentication establishes who a user is; authorisation decides what they may do. Store password hashes, never passwords — use a library, never your own hashing. Serve everything over HTTPS, because a session cookie sent over plain HTTP is readable by anyone on the same network. And check authorisation on the server for every write, on every request; hiding a delete button is presentation, not security.

Reading. The OWASP Top Ten — read the injection and access-control entries properly. The Flask documentation on request handling and configuration. Leaflet-Geoman's documentation for the drawing interface.

Measure before you optimise

Open the Network tab, hard-reload, and record three numbers: total bytes transferred, number of requests, and time until the map is usable. Then throttle the connection to "Slow 3G" and record them again. That second set is the real number for a large share of your users.

This is not an abstract concern in Kenya. Most users reach your map on a phone, over mobile data bought in bundles. A 40 MB GeoJSON is not merely slow — it consumes a measurable fraction of a monthly bundle to display one screen, and the user pays for the 39 MB they never see. A map that is expensive to open is a map that does not get opened. Payload is a design constraint, not a technicality, and it belongs in your project's requirements alongside the cartography.

Vector tiles

A vector tile is the same tile pyramid idea applied to geometry instead of pixels: each tile holds the features intersecting it, clipped, simplified to that zoom, and encoded compactly as protobuf (the MVT format). The browser draws them.

Compared with GeoJSON: only the visible area is transferred; each zoom gets appropriately generalised geometry; the encoding is far denser than JSON text; and styling stays client-side, so you can restyle instantly without re-fetching. Compared with raster tiles: features remain interactive and restylable, and the tiles are usually smaller.

The cost is complexity — you need something to generate and serve them (tippecanoe to build, pg_tileserv or ST_AsMVT to serve dynamically) and MapLibre GL rather than plain Leaflet to get the full benefit. The rule of thumb: under a few thousand features, GeoJSON with bbox filtering is simpler and fine. Above roughly ten thousand, vector tiles.

-- vector tiles straight from PostGIS, no tile server needed
WITH bounds AS (SELECT ST_TileEnvelope(%(z)s, %(x)s, %(y)s) AS geom),
     mvtgeom AS (
  SELECT ST_AsMVTGeom(ST_Transform(f.geom, 3857), bounds.geom) AS geom,
         f.id, f.name, f.level
  FROM facilities f, bounds
  WHERE ST_Intersects(ST_Transform(f.geom, 3857), bounds.geom)
)
SELECT ST_AsMVT(mvtgeom, 'facilities') FROM mvtgeom;

Cloud-native: the range request

One idea underlies the whole cloud-native geospatial movement. HTTP lets a client request part of a file — a byte range — rather than the whole thing. So if a file is organised so that its useful pieces sit in known places, a client can read just the pieces it needs, straight from cheap static storage, with no server-side software at all.

• COG — Cloud-Optimised GeoTIFF. A GeoTIFF internally tiled with overviews, and an index at the front. A client reads the header, works out which byte ranges hold the tiles it needs, and fetches only those. A 5 GB satellite scene becomes usable over the web without downloading it.
• PMTiles. An entire tile pyramid in a single file with an embedded directory. The client range-requests individual tiles. No tile server, no database — a static file on any web host. For a base map that changes rarely this is a strikingly good answer, and it removes an entire class of operational work.
• STAC. A JSON standard for cataloguing spatiotemporal assets, so a client can search "Sentinel-2 over Kiambu, June 2026, under 10% cloud" and get back COG URLs.

Reading. The Mapbox Vector Tile specification. The Cloud Optimized GeoTIFF and PMTiles project documentation. Crunchy Data's writing on ST_AsMVT. The Cloud-Native Geospatial Foundation's introductory material.

Getting it online

Two routes, and the choice follows from what you built.

• Static hosting — GitHub Pages, Netlify, Cloudflare Pages. If your map is HTML, CSS, JavaScript and data files with no server-side code, this is free, fast, HTTPS by default, and needs no maintenance. It cannot run your Flask API.
• A virtual private server — a small Linux machine you administer. Required once you have a database and an API. You install and maintain everything, and the machine is yours to secure.

On a VPS the pieces are: a WSGI server (gunicorn) running your Flask app; a reverse proxy (nginx) in front of it serving static files and terminating TLS; PostgreSQL; and a certificate from Let's Encrypt via certbot, which is free and automatic. Configuration lives in environment variables, never in the repository. Docker Compose is worth the afternoon it takes to learn, because it turns that whole stack into one file that runs identically on your laptop and the server — which is what makes "it worked on my machine" stop being a sentence you say.

HTTPS is not optional. Browsers restrict features on insecure origins — geolocation, among others, simply does not work over plain HTTP — and any credential sent over HTTP is readable by everyone between the user and your server.

OpenStreetMap

OSM is a free, editable map of the world built by volunteers. Its data model has three primitives and one organising idea:

• Node — a point with a coordinate. May carry tags, or exist only as part of a way.
• Way — an ordered list of nodes. Open for a road, closed for a building.
• Relation — an ordered list of members with roles: a bus route, a multipolygon with holes, an administrative boundary.
• Tags — free-form key/value pairs on any element. There is no fixed schema; conventions are documented on the wiki and enforced only by community agreement, which is both OSM's flexibility and its main data-quality problem.

Volunteered geographic information

Goodchild's phrase "citizens as sensors" named a genuine shift: the people who know a place best now have the tools to map it. The results can be extraordinary. Humanitarian OpenStreetMap Team mobilises remote volunteers to trace buildings and roads from imagery within hours of a disaster, and that data has routed real responders. Map Kibera, begun in 2009, is the case worth studying closely: Kibera appeared on official maps as a blank space, and residents mapped their own settlement — schools, clinics, water points, toilets — producing data that was used in service planning and advocacy. The people mapping were the people mapped.

Quality is the standing question. VGI has no formal accuracy specification and no accountable producer. In practice it is uneven in a predictable way: excellent where many contributors are active, thin where few are. Assess it as you would any dataset — check completeness against an independent source, look at edit history and contributor count, compare geometry against recent imagery, and be explicit in your report about what you checked. "It came from OSM" is a provenance statement, not a quality statement.

The ethics, which are not optional in this unit

A map is an intervention. It makes some things visible and leaves others out, and both have consequences for real people. Four issues arise directly in the projects you are building.

Locational privacy

A person's location over time is among the most sensitive data there is. It reveals where they live, work, worship, seek medical care, and who they associate with. Aggregate before publishing, coarsen precision, and think hard before mapping individuals at all. Note that de-identification is weaker than it looks: a "de-identified" set of home locations is trivially re-identifiable, because a home location is an identifier.

Mapping vulnerable people

Publishing precise locations of a group can expose them to targeting. This is not hypothetical: locations of refugees, of people receiving HIV care, of survivors of violence, of undocumented residents, of rhino populations. The rule is to ask who else can read this map and what they might do with it. Sometimes the correct professional decision is a coarser map, or no map.

Consent and benefit

If you map a community, did they agree, and do they gain? The distinction between mapping with a community and mapping it as a subject is the distinction between Map Kibera and extraction. This applies to student projects too: the residents whose settlement you map for coursework are not a dataset.

Absence is a decision

What a map omits shapes what gets funded and served. A settlement absent from official maps is absent from planning. Choosing what to include, and at what resolution, is an exercise of power, and pretending it is a neutral technical choice is itself a choice.

Reading. Goodchild (2007), "Citizens as sensors", GeoJournal 69(4). Hagen (2011) on Map Kibera, Innovations 6(1). The OSM wiki on the ODbL and on the licence's "produced work" distinction. Crampton, Mapping: A Critical Introduction to Cartography and GIS, ch. 1–3.

What a finished project looks like

Not "it runs on my laptop". A finished web mapping project has: a public URL over HTTPS; a README that a stranger can follow to a running instance; data whose source and licence are stated; secrets outside the repository; sensible behaviour when the network is slow or the API is down; and a map that is legible on a phone.

That last one is not a nicety. Test on an actual phone, on actual mobile data. A surprising number of otherwise good student projects are unusable on the device most of their users would have.

Reviewing code

You will review a peer's project and be reviewed. Useful review is specific and about the code, never the person. "This is confusing" is not review; "this function does three things — fetching, transforming and rendering — which makes the transform impossible to test on its own" is.

Work through in this order, because it puts the things that matter first:

1. Does it run? Follow the README exactly, on a clean machine, and note every place you had to guess.
2. Is it correct? Are areas and distances computed in a projected CRS? Are rates normalised? Is missing data distinguished from zero?
3. Is it safe? Parameterised queries? Secrets out of the client? Server-side validation on every write?
4. Is it usable? On a phone. On a slow connection. With a keyboard. In greyscale.
5. Is it maintainable? Could you add a layer next month without rereading everything?

What to carry out of this unit

The specific technologies will move. Leaflet may be displaced by MapLibre; GeoServer is already optional for a large class of problems that PMTiles solves more simply. What will not move is the structure underneath: a tile pyramid; a projection with known distortions; a client and a server with a network between them that is slower and more expensive than you think; a database that is better at spatial questions than your application code will ever be; and a user on a phone, paying for every megabyte you send.

And one more thing, which is the reason week 10 is in this unit at all: the map you build will be read as true. That is what maps do. Building them carefully — normalising the right denominator, distinguishing missing from zero, thinking about who is exposed by what you publish — is not extra credit. It is the job.

Reading. Monmonier, How to Lie with Maps, 3rd ed. — the whole book, and it is short. Nielsen's usability heuristics, applied to your own interface.

Your programming unit was in Python. This unit is in JavaScript and SQL. Work through the tasks below before week 2, without help of any kind — no notes, no search, no AI assistant. The point is to find out what you have, and using help defeats it entirely.

JavaScript — eight tasks

1. Declare a constant holding an array of five numbers. Print its length.
2. Write a function that takes an array of numbers and returns their mean. Write it twice — once with a for loop, once with reduce.
3. Given an array of objects each with name and beds, return an array of just the names of those with more than 100 beds. Use filter and map.
4. Explain in one sentence what const x = {a: 1}; x.a = 2; does, and why it is not an error.
5. Write a template literal producing "Nairobi has 34 facilities" from variables county and n.
6. Explain what this prints, and why:
   console.log("5" == 5, "5" === 5);
7. Write an async function that fetches JSON from a URL, throws on a non-200 status, and returns the parsed object.
8. Explain what is wrong here and fix it:
   let d; fetch(u).then(r => r.json()).then(j => d = j); console.log(d.length);

SQL — six tasks

1. Select the name and population of all counties with population above one million, ordered descending.
2. Count the rows in facilities grouped by level.
3. Join facilities to counties on county_id and return county name with facility count. Include counties with zero facilities.
4. Explain the difference between WHERE and HAVING, with an example of each.
5. Explain the difference between an INNER JOIN and a LEFT JOIN, and say which task 3 needs.
6. Explain what is dangerous here and rewrite it safely:
   cur.execute(f"SELECT * FROM users WHERE name = '{n}'")

Tasks JS 1–5 and SQL 1–3 are the floor. JS 6–8 and SQL 4–6 are the working level for this unit — JS 8 is week 2's central concept and SQL 6 is week 8's.

Six things that will actually bite you

• this in JavaScript. It means different things in different call contexts. Arrow functions inherit this from where they were written, which is nearly always what you want — prefer them in callbacks.
• == versus ===. The double equals coerces types, so "" == 0 is true and null == undefined is true. Use === always, without exception.
• Everything asynchronous is asynchronous. If a value is undefined right after a fetch, nothing is broken — the fetch has not finished. Week 2 covers this properly.
• SQL is declarative. You describe the result you want; the planner decides how to get it. Do not write loops in SQL. If you are reaching for a cursor, you are usually one JOIN or one window function away from the right answer.
• NULL is not a value. NULL = NULL is not true, it is NULL. Use IS NULL. This bites in outer joins, where the absent side is all nulls.
• Semicolons and braces. JavaScript will insert semicolons for you in ways that occasionally surprise. Use a formatter — Prettier is one click in VS Code — and stop thinking about it.

Where to go

• MDN Web Docs — the reference for everything browser-side. Its "JavaScript first steps" and "Using Fetch" guides cover most of what this unit needs.
• Eloquent JavaScript by Marijn Haverbeke, chapters 1–5 and 11 (promises), free online. The best free route into the language properly.
• PostgreSQL Tutorial and Select Star SQL — both free, both practical.
• The Leaflet tutorials — short, well written, and they teach JavaScript patterns alongside the mapping.

Coordinate reference systems you will use

HTTP status codes worth recognising

The errors you will actually hit

Leaflet, minimum viable

L.map(id, opts)                    // create; opts: center, zoom, preferCanvas
map.setView([lat, lng], zoom)      // LATITUDE FIRST
map.fitBounds(bounds, {padding})   // let the data set the view
L.tileLayer(urlTemplate, {attribution, maxZoom})
L.tileLayer.wms(url, {layers, format, transparent: true, version})
L.marker(latlng, {icon}) · L.circleMarker(latlng, {radius, fillColor})
L.geoJSON(data, {style, pointToLayer, onEachFeature, filter})
layer.bindPopup(html) · layer.bindTooltip(text)
map.on("moveend"|"click"|"zoomend", handler)
L.control.layers(baseLayers, overlays).addTo(map)

PostGIS, minimum viable

ST_Intersects(a,b) · ST_Within(a,b) · ST_Contains(a,b)
ST_DWithin(a,b,d)                  -- index-aware; prefer over ST_Distance < d
ST_Distance(a,b) · ST_Area(g) · ST_Length(g)     -- units follow the CRS!
ST_Transform(g, srid) · g::geography             -- one of these, every time
ST_Buffer(g,d) · ST_Centroid(g) · ST_Simplify(g,tol)
ST_SimplifyPreserveTopology(g,tol)               -- for adjacent polygons
ST_IsValid(g) · ST_MakeValid(g)
ST_AsGeoJSON(g, precision) · ST_AsMVT(rows, name)
ST_SRID(g) · ST_SetSRID(g, srid) · ST_MakeEnvelope(...)
a && b                             -- bbox overlap; uses the index
a <-> b                            -- distance operator, for KNN with ORDER BY
CREATE INDEX x ON t USING GIST (geom);

Free services you can rely on

All datasets are distributed through the unit's shared folder with a README giving CRS, provenance and licence for each. Check the licence before reusing anything outside this unit — the OSM extract carries ODbL obligations that follow it into whatever you build.

EGE 2531 Web Mapping · Course reader, edition 1.0 · Jomo Kenyatta University of Agriculture and Technology · September 2026. Corrections and suggestions are welcome and will be credited in the next edition.