You have a spreadsheet export with a column called Breitengrad, or enlem;boylam with decimal commas, or 40°26′46″N 79°58′56″W strings, or Plus Codes, or MGRS references. geocsv finds the coordinates, tells you how sure it is and why, reports the rows that are broken, and writes a file that QGIS, ArcGIS, Google Earth, a GPS or a web map can open. It is pure Python with no required dependencies.

📦 Installation

pip install geocsv

# optional extras
pip install "geocsv[pyproj]"     # reproject x/y or EWKT from any EPSG code
pip install "geocsv[shapefile]"  # write ESRI Shapefiles (via pyshp)

Python 3.9+ on Windows, macOS or Linux.

⚡ Quickstart

geocsv inspect places.csv                 # what was detected, and which rows are wrong
geocsv convert places.csv -o places.gpkg  # GeoPackage (also .geojson .geojsonl .kml .gpx .shp)
geocsv convert places.csv -o places.geojson --lat "Y koord" --lon "X koord"

import geocsv

table = geocsv.read("places.csv")
print(table.detection.describe())
# latlon: lat='Breitengrad', lon='Längengrad', decimal (confidence 0.99)
print(table.report())

table.to_gpkg("places.gpkg")
table.to_geojson("places.geojson")
fc = table.to_geojson()          # or get the FeatureCollection as a dict
table.to_kml("places.kml")
table.to_gpx("places.gpx")

geocsv.detect("places.csv")      # detection only, with .reasons and .alternatives

🔎 What it reads

CSV dialects (standard library only)

• encodings: UTF-8, UTF-8 with BOM, UTF-16 (Excel "Unicode text"), and the Windows code pages cp1252 / latin-1 / cp1254 (Turkish letters such as ğ ı ş are told apart from Western European text)
• delimiters , ; tab | (sniffed from the data, quoted fields respected) and Excel's sep=; first line
• decimal commas (40,7128), header or no header (detected), ragged rows

Geometry encodings, found automatically:

Every detection has a confidence and human-readable reasons:

$ geocsv detect stations.csv
latlon: lat='lon', lon='lat', decimal (confidence 0.99)
  - header 'lat' looks like latitude but its values only fit longitude; the columns are swapped
  - 100% of values are coordinates; 100% are within latitude/longitude range
  - the two columns are adjacent

Override any decision: lat=/lon=, wkt=, column= + kind=, x=/y= + epsg=, order="lonlat", encoding=, delimiter=, header= (CLI: --lat, --lon, --wkt, --column, --kind, --x, --y, --epsg, --order, --encoding, --delimiter, --header/--no-header). Columns can be named or numbered from 1.

🩺 Validation report

$ geocsv inspect issues.csv
Geometry   latlon: lat='latitude', lon='longitude', decimal (confidence 0.87)
Valid      8 of 13 rows  bbox=(0.000000, 0.000000, 37.874600, 41.008200)

issue           severity   rows  lines
--------------  --------  -----  --------------------
missing         error         2  3, 4
invalid         error         1  5
out_of_range    error         1  6
swapped         error         1  9
likely_swapped  warning       1  13
null_island     warning       1  7
duplicate       warning       1  8
ragged          warning       1  14

Line numbers are physical lines in the file, as your editor shows them. table.issues, table.summary() and geocsv inspect --json give the same data in machine-readable form; geocsv convert --strict exits with status 1 when any row has an error.

🗺️ What it writes

Attributes keep their types: integer, real or text (codes like "00123" stay text). A name-like column (name, title, isim, nombre, …) labels KML placemarks and GPX waypoints. The GeoPackage writer is tested against sqlite3, GDAL's ogrinfo, GDAL's validate_gpkg.py conformance checker and GeoPandas.

🧭 Coordinate helpers

The decoders are public and dependency-free:

from geocsv import dms, geohash, pluscode, maidenhead, utm

dms.parse_dms_pair("40°26′46″N 79°58′56″W")   # (40.4461, -79.9822)
dms.format_dms(40.446111, "lat")             # '40°26′46.0″N'
geohash.decode("u4pruydqqvj")                # (57.64911, 10.40744)
pluscode.decode("849VCWC8+R9")               # (37.4220625, -122.0840625)
pluscode.recover_nearest("CWC8+R9", 37.4, -122.0)
maidenhead.decode("FN31pr")                  # (41.7292, -72.7083)
utm.mgrs_to_latlon("31U DQ 48251 11932")     # (48.8582, 2.2945)
utm.latlon_to_mgrs(48.8582, 2.2945)          # '31U DQ 48251 11932'
utm.utm_to_latlon(31, "N", 448251, 5411932)

UTM/MGRS use Krüger's series to sixth order; they agree with PROJ to under a millimetre.

🛠️ Development

git clone https://github.com/YusufEminoglu/geocsv_sdk.git
cd geocsv_sdk
pip install -e ".[dev,pyproj,shapefile]"
python -m pytest --cov=geocsv
python -m ruff check . && python -m ruff format --check src tests && python -m mypy src

The tests include hand-made fixture CSVs, reference values for every decoder, a seeded synthetic corpus of 400 tables that measures detection accuracy, and GDAL-based checks of the GeoPackage output that run when GDAL is installed.

📄 License

MIT © Yusuf Eminoğlu