# Geo Data Visualizer

> Map CSV coordinates or GeoJSON as points, proportional circles, hex-bin heatmaps or choropleths. Upload a CSV/XLSX with latitude/longitude (plus optional value and label) or a country-code column, or a GeoJSON file with points, lines and polygons. Get an SVG map over bundled Natural Earth country outlines in the Equal Earth, Mercator or equirectangular projection – as points, proportional symbols, a hexagonal-bin heatmap or a choropleth – zoomed to your data, with SVG/PNG downloads.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://geodatavisualizer.usefulweb.site/ (interactive tool at https://geodatavisualizer.usefulweb.site/tool)
- JSON API: POST https://geodatavisualizer.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://geodatavisualizer.usefulweb.site/api/v1/tool)
- OpenAPI: https://geodatavisualizer.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://geodatavisualizer.usefulweb.site/mcp - tool `geo_data_visualizer`

## Inputs
- file (file): CSV, Excel or GeoJSON file - Max 20 MB. CSV/XLSX: lat/lon columns or a country column (ISO code or English name). GeoJSON: Point, LineString, Polygon (and Multi-) geometries.
- data (textarea): Or paste data - CSV with a header row, or GeoJSON.
- mode (select): Map type
- projection (select): Projection
- latColumn (text): Latitude column - Empty: a column named lat/latitude.
- lonColumn (text): Longitude column - Empty: a column named lon/lng/longitude.
- valueColumn (text): Value column / property - Numbers for circle size, hex sums or choropleth shading. Empty: the first numeric column (or a "value" property in GeoJSON).
- labelColumn (text): Label column / property
- countryColumn (text): Country column (choropleth) - ISO 3166 alpha-2/alpha-3 codes or English country names.
- zoom (select): Extent
- hexRadius (integer): Hexagon size
- title (text): Map title
- png (boolean): Also create a PNG image

## Method
- Input detection: text starting with "{" is read as GeoJSON (FeatureCollection, Feature or bare geometry; Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection). Anything else is a table (CSV/TSV/XLSX); lat/lon and country columns are found by name unless you name them.
- Coordinates must be WGS 84 decimal degrees (longitude −180…180, latitude −90…90); rows outside the range or without numbers are skipped and counted.
- Projections: equirectangular x = λ, y = φ; Mercator y = ln tan(π/4 + φ/2) (clipped at ±85°); Equal Earth (Šavrič, Patterson & Jenny 2018), an equal-area projection suitable for world maps and for comparing densities.
- Auto zoom fits the bounding box of the data plus 20 % margin (at least 4° × 3°); views wider than 300° of longitude show the whole world.
- Hex-bin heatmap: points are projected, assigned to pointy-top hexagons of the chosen pixel size (cube-coordinate rounding) and coloured by count, or by the sum of the value column, on a colour-blind-safe viridis-like ramp.
- Proportional circles: circle area is proportional to |value| (radius ∝ √value, largest 26 px); larger circles are drawn first so small ones stay visible. Choropleth: country codes/names are matched to the bundled outlines and shaded in up to five quantile classes; unmatched entries are listed.
- Country outlines are Natural Earth 1:110m (public domain): small countries and islands such as Singapore, Malta or Andorra are not part of this scale and cannot be shaded. Borders follow Natural Earth’s de facto conventions and are not a statement on disputed territories.