Skip to main content

CSV Reader

Overview​

Geoflip can read geospatial data from CSV files where geometry is supplied as WKT. This is useful for lightweight exports from databases (e.g., Snowflake/Postgres), spreadsheets, or logs.

Key points

  • Required CRS: you must supply an EPSG code with the request (same as DXF).
  • Required geometry field: CSV must contain a column named geom_wkt containing valid WKT.
  • If geom_wkt is missing or invalid, the job currently fails with a server error (known limitation; better errors coming).

Requirements​

CSV file format​

  • Delimiter: , (comma).
  • Header row: required (first row with column names).
  • Geometry column: geom_wkt (case sensitive).
  • Encoding: UTF-8 recommended.
  • Coordinate reference system: specified via request as an EPSG code (e.g., EPSG:4326). All WKT coordinates in the CSV are assumed to be in this CRS.

Supported WKT:

  • POINT, LINESTRING, POLYGON
  • Multi-geometries: MULTIPOINT, MULTILINESTRING, MULTIPOLYGON
  • Optional Z values (e.g., POINT Z (...)) are ignored unless a downstream transformation requires Z.

Example CSV​

id,name,geom_wkt
1,Site A,POINT(115.857 -31.953)
2,Haul Road,LINESTRING(115.85 -31.95,115.86 -31.94,115.87 -31.935)
3,Tenement 42,POLYGON((115.84 -31.96,115.88 -31.96,115.88 -31.93,115.84 -31.93,115.84 -31.96))

In this example, coords are long,lat in EPSG:4326.

Request Payload​

Minimal JSON body (referencing an uploaded CSV)​

{
  "input_format": "csv",
  "input_epsg": "EPSG:4326",
  "output_format": "geojson",
  "output_crs": "EPSG:4326",
  "csv_options": {
    "geometry_column": "geom_wkt",
    "delimiter": ",",
    "has_header": true,
    "encoding": "utf-8"
  },
  "transformations": [
    { "type": "buffer", "distance": 100, "units": "meters" }
  ]
}

Field notes​

  • input_format: must be "csv".
  • input_epsg (required): EPSG code of the coordinates in geom_wkt.
  • csv_options.geometry_column: defaults to "geom_wkt". Keep it unless you also change your CSV header and server config.
  • output_format: any format your API supports (e.g., geojson, dxf, gpkg, shp).
  • output_crs: target EPSG (reprojection happens internally).
  • transformations: same contract as other inputs (e.g., buffer, clip, union).

Example: cURL (multipart form upload)​

curl -X POST https://api.geoflip.io/transform \
  -F "file=@/path/to/data.csv;type=text/csv" \
  -F 'payload={
    "input_format":"csv",
    "input_epsg":"EPSG:4326",
    "output_format":"geojson",
    "output_crs":"EPSG:3857",
    "csv_options":{"geometry_column":"geom_wkt","delimiter":",","has_header":true},
    "transformations":[{"type":"buffer","distance":100,"units":"meters"}]
  }'

Example: referencing a file by URL (if supported)​

{
  "input_format": "csv",
  "input_epsg": "EPSG:7855",
  "input_url": "https://example.com/exports/machines.csv",
  "output_format": "gpkg",
  "output_crs": "EPSG:7855",
  "transformations": [
    { "type": "clip", "clipping_geojson": { "type":"Polygon","coordinates":[[...] ] } }
  ]
}

CRS & Units​

  • input_epsg (required) tells Geoflip how to interpret the WKT coordinates.
  • Geoflip will reprojection-chain your data to output_crs before writing the result.
  • Transformation units (meters, kilometers, etc.) behave the same as with other inputs. For metric buffers, prefer a projected CRS (e.g., GDA2020 / MGA zone; EPSG:78xx) to avoid distortion.

Transformations​

CSV input supports the same transformation types you’ve enabled for GeoJSON/SHP/DXF (e.g., buffer, clip, union, dissolve, reproject, etc.). There are no CSV-specific differences beyond the geometry ingestion step.

Responses​

  • 202 Accepted (async): returns a job_id. Fetch results via your standard /result/output/{job_id} endpoint.
  • 200 OK (sync, if enabled): returns transformed data or a handle to download it.

Known limitation: If geom_wkt is missing or contains invalid WKT in any row, the job may be marked failed with a server error (5xx) rather than a clear validation error. See “Troubleshooting” below.

Validation & Troubleshooting​

Common issues

  1. Missing geom_wkt column

    • Symptom: job fails with a server error (5xx) despite request being accepted.
    • Fix: ensure the CSV header contains an exact geom_wkt column (or set csv_options.geometry_column to match your file).

  2. Invalid WKT

    • Symptom: server error or partial read failures (depending on parser tolerance).
    • Fix: validate WKT before upload (e.g., ST_IsValid, Shapely loads, GEOS).

  3. Wrong EPSG

    • Symptom: features appear in the wrong location after transform (e.g., off the coast).
    • Fix: confirm input_epsg matches the coordinate system used to create the WKT.

  4. Delimiter or header mismatch

    • Symptom: zero features or misaligned attributes.
    • Fix: ensure delimiter matches the file and has_header=true when a header is present.

When exporting CSV from databases or tools, prefer:

  • ST_AsText(geom) as geom_wkt
  • Explicit numeric precision suitable for your CRS (6–8 decimal places for lon/lat)
  • UTF-8 encoding
  • Comma delimiter with quoted strings where needed