Skip to content

World Map API

Access the global civil-solar deviation map in multiple formats.

GET /world/deviation-map

Returns a grid of civil-solar offset values for every ~0.5° point on Earth. Available in JSON, CSV, and GeoJSON formats.

Parameters

Parameter Required Type Description
format No string json (default), csv, geojson
resolution No float Grid resolution in degrees (default: 0.5)

Examples

curl "http://localhost:8090/world/deviation-map?format=json"

curl "http://localhost:8090/world/deviation-map?format=csv" -o deviation.csv

curl "http://localhost:8090/world/deviation-map?format=geojson" -o deviation.geojson

JSON Response Structure

{
  "generated_utc": "2026-04-14T12:00:00Z",
  "resolution_deg": 0.5,
  "points": [
    {
      "lat": -90.0,
      "lng": -180.0,
      "utc_offset_h": -12,
      "solar_utc_offset_h": -12.0,
      "civil_solar_offset_min": 0
    },
    ...
  ]
}

CSV Column Schema

lat,lng,utc_offset_h,solar_utc_offset_h,civil_solar_offset_min
51.5,-0.1,1,0.82,-10.6
39.47,75.99,8,5.07,-175.0

GeoJSON Structure

Each point is a GeoJSON Feature with properties:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-0.1, 51.5]},
      "properties": {
        "utc_offset_h": 1,
        "solar_utc_offset_h": 0.82,
        "civil_solar_offset_min": -10.6
      }
    }
  ]
}

Interpreting the Data

civil_solar_offset_min Interpretation
0 Civil noon = solar noon (perfect alignment)
+60 Civil clock runs 1h ahead of the Sun (western edge effect)
−175 Civil clock runs 2h 55m behind the Sun (Kashgar, China)

Research Use

The CSV export is designed for epidemiological research. It provides the civil_solar_offset_min variable that Roenneberg et al. identified as missing from public health datasets at sub-timezone resolution.