Skip to main content

Import

The import API turns a data file into a table. You upload one or more files, such as CSV, GeoJSON, GeoParquet, FlatGeobuf, a zipped shapefile, a GeoPackage, a MapInfo table or a File Geodatabase, to temporary storage, then ask the server to process them into a target schema and table. The server reads the file with GDAL/OGR, so most vector and tabular formats are accepted, coordinate reference systems can be set or reprojected on the way in, and a dry run validates the result before anything is written.

This is the quickest way to get existing data into Centia.io, whether you are seeding a new backend, appending a monthly delivery to an existing table or loading a dataset for a map. Spatial files become tables with a geometry column and are immediately available through SQL and the OGC services.

To import from a URL on a recurring schedule instead, use the Scheduler.

The flow is typically two steps:

  1. Upload the file(s) using multipart/form-data to get them staged on the server.
  2. Process the uploaded file into a target schema/table with desired options (dry-run, append, SRS, etc.).

Upload files​

Uploads one or more files to be processed later.

Upload a file for later import
POST https://api.centia.io/api/v4/file/upload HTTP/1.1
Authorization: Bearer abc123
Content-Type: multipart/form-data

[attach file as form field: filename]
Upload using curl
curl \
  -X POST "https://api.centia.io/api/v4/file/upload" \
  -H "Authorization: Bearer abc123" \
  -F "filename=@./mydata.csv"
note
  • Cli will compress the selected file or directory and upload/process in one step.
  • File can be a zip archive containing multiple files in subdirectories
  • File format is determined by the file extension (e.g. .csv, .geojson, .parquet, .fgb, .gpkg, .zip)
  • File formats with multiple parts (ESRI Shapefile, MapInfo TAB) and directory-based formats (File Geodatabase .gdb) must be zipped

Responses

  • 201 Created on successful processing

Process/import uploaded file​

Imports the previously uploaded file into a database schema. You can run a dry-run by setting import to validate before committing.

Dry-run import (no changes written)
POST https://api.centia.io/api/v4/file/process HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer abc123

{
  "file": "mydata.csv",
  "import": false
}
Commit import (write data to table)
POST https://api.centia.io/api/v4/file/process HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer abc123

{
  "file": "mydata.csv",
  "schema": "my_schema",
  "import": true
}

General parameters

  • file: File name previously uploaded with /file/upload (required)
  • schema: Destination schema (required if import is true)
  • import: If false, perform dry-run only. If true, commit import. Default: true
  • append: Append to an existing table instead of creating a new one. Default: false
  • truncate: Truncate table before appending (only effective with append). Default: false
  • timestamp: Name of timestamp field to create on import (omit to skip)

PostGIS import Parameters

  • t_srs: Fallback target SRS. Will be used if no authority name/code is available. Default: EPSG:4326
  • s_srs: Fallback source SRS. Will be used if file doesn't contain projection information.
  • p_multi: Promote single geometries to multi-part. Default: false
  • x_possible_names: Possible column names for X/longitude in CSV. Default: "lon*,Lon*,x,X"
  • y_possible_names: Possible column names for Y/latitude in CSV. Default: "lat*,Lat*,y,Y"

Responses

  • 201 Created on successful processing
  • 404 Not found if the file or target cannot be processed

Geospatial formats and PostGIS import​

This service can import common geographic file formats and create fully usable PostGIS tables in your schema. Below is how each is handled and what to expect in the resulting table(s).

Supported formats

  • GeoJSON (.geojson): Single layer. Geometry type is detected. Source SRID defaults to EPSG:4326 (GeoJSON default). Attributes are imported as text/number/boolean where possible.
  • ESRI Shapefile (.shp): Must be uploaded as a .zip including all sidecar files (.dbf, .shx, .prj, etc.). One PostGIS table is created per shapefile.
  • GeoPackage (.gpkg): May contain multiple layers. One PostGIS table is created per layer.
  • FlatGeobuf (.fgb): Single layer. Geometry type and CRS are read from the file header. This is also one of the formats snapshots can be exported in.
  • MapInfo TAB (.tab): Must be uploaded as a .zip including all sidecar files (.dat, .map, .id, .ind). One PostGIS table is created per TAB file.
  • ESRI File Geodatabase (.gdb): A directory; zip the whole .gdb folder. May contain multiple feature classes. One PostGIS table is created per feature class.
  • Parquet / GeoParquet (.parquet): Single layer. A GeoParquet file carries its geometry column, geometry type and CRS in the file metadata, and these are used as-is. A plain Parquet file without geometry metadata is imported as a table without a geometry column. This is also the format snapshots are exported in, so a snapshot of one table can be imported into another.
  • Geography Markup Language (.gml): May contain multiple layers. One PostGIS table is created per layer.
  • CSV (.csv): If the file contains coordinates, a geometry column will be constructed. See CSV geometry detection below.

How data becomes a PostGIS table

  • Table name: Derived from the source layer or file name. When appending, the existing table name is reused.
  • Geometry column: Named geom. Geometry type is inferred (e.g., Point, LineString, Polygon). Use p_multi: true to promote single to multi-part types when needed (e.g., MultiPolygon).
  • SRID (projection):
    • If the source has an authority/code (e.g., EPSG:25832), it will be preserved.
    • If the source lacks authority/code but has projection info, t_srs is used for the target table, and the geometry will be assigned/transformed accordingly.
    • If no projection info can be determined, s_srs is used as source SRID.
  • Attributes: Field types are inferred where possible (integer, numeric, text, boolean, timestamp). The optional timestamp property can add a created timestamp column.
  • Indices: A standard GiST index on the geometry column is created by the platform. If you append, existing indices are preserved; new indices are not recreated unless needed.
  • A primary key is added to the table named 'gid'.

Multiple layers in one upload

  • Zip with multiple shapefiles: Each shapefile becomes a separate table.
  • GeoPackage and Geography Markup Language with multiple layers: Each layer becomes a separate table.
  • File Geodatabase with multiple feature classes: Each feature class becomes a separate table.

Append and truncate semantics

  • append: true will insert features into an existing table (schema.table). The table must be compatible (same or castable attribute types and geometry type/SRID).
  • truncate: true can be combined with append to clear the table before loading new data.

CSV geometry detection

  • The importer will look for X/longitude and Y/latitude columns when the format is CSV.
  • You can control the column name patterns via x_possible_names and y_possible_names. Defaults are:
    • x_possible_names: "lon*,Lon*,x,X"
    • y_possible_names: "lat*,Lat*,y,Y"
  • If a matching pair is found, a Point geometry in the target SRID is created from those columns. If not, the CSV is imported without a geometry column.

Examples

Import a zipped Shapefile as MultiPolygon and assign EPSG:4326 if missing
# 1) Upload
curl -X POST "https://api.centia.io/api/v4/file/upload" \
  -H "Authorization: Bearer abc123" \
  -F "filename=@./parcels.zip"

# 2) Process (commit)
curl -X POST "https://api.centia.io/api/v4/file/process" \
  -H "Authorization: Bearer abc123" \
  -H "Content-Type: application/json" \
  -d "{\n  \"file\": \"parcels.zip\",\n  \"schema\": \"cadastre\",\n  \"import\": true,\n  \"p_multi\": true,\n  \"s_srs\": \"EPSG:4326\"\n}"
Import a CSV with lon/lat columns into my_schema.points
# 1) Dry-run to validate coordinate detection
centia import ./points.csv --dry_run
# 2) Commit
centia import ./points.csv my_schema
Import a GeoParquet file into my_schema
# 1) Upload
curl -X POST "https://api.centia.io/api/v4/file/upload" \
  -H "Authorization: Bearer abc123" \
  -F "filename=@./buildings.parquet"

# 2) Process (commit). The CRS is read from the GeoParquet metadata, so s_srs is only a fallback.
curl -X POST "https://api.centia.io/api/v4/file/process" \
  -H "Authorization: Bearer abc123" \
  -H "Content-Type: application/json" \
  -d "{\n  \"file\": \"buildings.parquet\",\n  \"schema\": \"my_schema\",\n  \"import\": true,\n  \"p_multi\": true\n}"