Convert a File
POST/api/geoconvert/convert/file
Convert an uploaded file between any supported formats (any to any). The input is detected automatically from the file extension:
.geojson/.json→ GeoJSON,.kml→ KML,.kmz→ KMZ,.gpx→ GPX,.gpkg→ GeoPackage.csv,.dxf,.gml,.fgb,.geojsonl,.sqlite,.parquet,.ods,.xlsx→ their matching formats.zip(a zipped shapefile containing.shp/.shx/.dbf/.prj) → read as Shapefile. A ZIP wrapping a single other-format file (a zipped KML download, for example) is unwrapped and converted as that file automatically. A ZIP holding several convertible files is rejected with a listing of its contents — convert them one at a time here, or drop the ZIP on the upload page to map each file to its own target.
The output is chosen with the optional outputFormat field (see below). When omitted, the historic defaults apply (GeoJSON → Shapefile, Shapefile → GeoJSON, everything else → GeoJSON). Conversions a format cannot represent (for example area shapes into GPX) are rejected with a plain-language explanation in error.
This is the recommended endpoint for programmatic use. The usage fields (remainingConversions, remainingBytes, newWalletBalanceCents) stay null unless you pass includeWallet=true; /convert/upload is a legacy alias with them always included.
Headers
X-API-Key(required for authentication)
Request (multipart/form-data)
file file (required)
The input file, in any of the supported extensions listed above. A shapefile zip must include at least .shp, .shx and .dbf; a missing .prj means the source CRS is unknown, so pass sourceEpsg to say what the coordinates are in. Single-file formats may also arrive wrapped in a ZIP and are unwrapped automatically.
outputFormat string (optional)
The target format to produce, case-insensitive. Omit to use the default direction (GeoJSON ↔ Shapefile). Must differ from the detected input format. Supported values:
GeoJson, Shapefile, Csv, Gml, GeoPackage, Gpx, Kml, Kmz, FlatGeobuf, GeoJsonSeq, Dxf, MapInfo, Ods, Xlsx, SpatiaLite, GeoParquet, OpenFileGdb, Wkt.
Directory-based formats (Shapefile, MapInfo, OpenFileGdb) are returned as a single .zip. Availability of GeoParquet and OpenFileGdb depends on the GDAL build on the conversion host.
targetEpsg number (optional)
Target EPSG code. Defaults to 4326. GeoJSON output is always WGS84 (EPSG:4326) per RFC 7946.
sourceEpsg number (optional)
The EPSG code the input's coordinates are already in. Most formats record their own coordinate system, so omit this — passing it overrides what the file says.
It is required for inputs that record none at all: .dxf CAD drawings and the plain table formats (.csv, .xlsx, .ods), plus a shapefile ZIP that arrives without its .prj. Coordinates with no known system cannot be placed on the Earth, so a conversion that needs to reproject them is rejected rather than guessed at.
includeWallet boolean (optional)
When true, the response's usage fields (remainingConversions, remainingBytes, newWalletBalanceCents) are populated after the conversion; otherwise they are null. Defaults to false. (The field keeps its historical name so existing clients need no change.)
Response 200
success boolean
True when the conversion completes successfully.
jobId string
Job identifier for status polling.
status string
Current job status (e.g. Completed, Failed).
inputFormat string
Detected input format token (e.g. geojson, shapefile, kml, gpx).
outputFormat string
The GDAL driver token for the produced output (e.g. shapefile, geojson, gpkg, kml), reflecting the resolved target.
downloadUrl string
Presigned URL for the output. Directory formats (Shapefile, MapInfo, File Geodatabase) arrive as a .zip; single-file formats use the format's own extension (e.g. .geojson, .gpkg).
downloadExpiresAt string
Expiration timestamp for the download link (ISO 8601).
featureCount number
Number of features detected in the input by GDAL.
geometryType string
Detected geometry type (Point, LineString, Polygon, …).
processingTimeMs number
Processing duration in milliseconds.
outputSizeBytes number
Size of the generated output in bytes.
remainingConversions number | null
Conversions left in the plan's monthly allowance after this one. Populated only when includeWallet=true (always populated on /convert/upload); null otherwise, and null on an account still spending legacy prepaid credit, which has no monthly allowance.
remainingBytes number | null
Input bytes left in the plan's monthly data allowance after this one. Populated under the same rules as remainingConversions.
newWalletBalanceCents number | null
Only for accounts still spending legacy prepaid credit: the balance in USD cents after the conversion. null on every plan.
truncationReport object | null
Present when the target is Shapefile (the only lossy direction) — the same data-loss report returned by /convert/analyze (field-name truncation/collisions, value truncation, geometry coercions). null for all other targets. You receive this even if you never call /analyze — it simply arrives after the conversion rather than before it.
error string
Present when the conversion fails, describing the reason. A failure is still HTTP 200 with success: false; the flags below say what kind it is so a client can act rather than parse the text.
needsUpgrade boolean, limit string
needsUpgrade is true when a plan limit refused the conversion, and limit says which: fileSize (over the plan's per-file cap), data (this month's data allowance), conversions (this month's conversion allowance) or wallet (legacy prepaid credit does not cover the file). A bigger plan lifts the limit; otherwise the allowance resets next month. limit is access when the account may not convert at all (see paymentPastDue). Nothing was counted.
paymentPastDue boolean
true when the account's payment is past due; conversions are refused until the payment method is updated on the GeoConvert dashboard.
multiLayer boolean, targetFormat string, layers array
multiLayer is true when the uploaded archive holds several layers and targetFormat stores only one; layers lists them as { layer, features }. Export the layer you need to its own file, or pick a multi-layer target such as GeoPackage. Nothing was counted.
curl -X POST https://cadshift.com/api/geoconvert/convert/file -H "X-API-Key: $API_KEY" -F "[email protected]"curl -X POST https://cadshift.com/api/geoconvert/convert/file -H "X-API-Key: $API_KEY" -F "[email protected]" -F "outputFormat=GeoPackage"curl -X POST https://cadshift.com/api/geoconvert/convert/file -H "X-API-Key: $API_KEY" -F "[email protected]" -F "outputFormat=GeoJson" -F "sourceEpsg=32633"A DXF holds bare drawing coordinates. sourceEpsg is what says they are metres in UTM zone 33N; without it there is nothing to reproject from.
{
"success": true,
"jobId": "00000000-0000-0000-0000-000000000000",
"status": "Completed",
"inputFormat": "shapefile",
"outputFormat": "geojson",
"downloadUrl": "https://...",
"downloadExpiresAt": "2026-01-01T00:00:00Z",
"featureCount": 177,
"geometryType": "Polygon",
"processingTimeMs": 1840,
"outputSizeBytes": 1100647,
"remainingConversions": null,
"remainingBytes": null,
"newWalletBalanceCents": null,
"truncationReport": null
}