Import API

Import geometries and unit tables through upload, preview and confirmation steps.

Last updated: 10 November 2026

Two separate import workflows

Files with geometry use /import; address and building unit tables use /birim-aktarim. Both require a session and write permission. Geometry imports without a source selection create new features. An import linked to a data source can support controlled reimport by comparing the previous source, new file and local record.

Uploading a geometry file

POST /api/p/{pid}/import accepts a multipart file field. Supported formats are KML, KMZ, GeoJSON/JSON, zipped Shapefile or FileGDB, CSV/TXT, DXF, GeoPackage and DGN V7. Read the formats enabled in the installation from GET /api/meta. XLSX is not an input format for this geometry workflow.

FileGDB curves are converted to lines; original CAD curve definitions are not retained in this format. Compare returned uyarilar, donusumler, skipped and source_total with the source. Multiple alternative datasets in one ZIP are not accepted as a single upload.

Browser example with an active session:

const form = new FormData();
form.append('file', dosya);
const yanit = await fetch(`/api/p/${projeId}/import`, {
  method: 'POST',
  credentials: 'same-origin',
  body: form
});
const sonuc = await yanit.json();
if (!yanit.ok) throw new Error(sonuc.detail);

dosya is the user-selected File; projeId is an accessible project identifier. Main response fields:

Upload does not yet create project features. Review each group's suggest and field_map before confirming.

Mapping and committing

The JSON body for POST /api/p/{pid}/import/{token} contains crs and groups. Keys in groups are the actual key values from the upload response. This example assumes a source group named CSV·Point with an Ad column:

{
  "crs": "EPSG:4326",
  "groups": {
    "CSV·Point": {
      "target": "building",
      "name_field": "Ad",
      "status": "existing",
      "fields": {}
    }
  }
}

target can be a catalogue type matching the geometry, ref or skip. ref accepts an optional layer_name. fields maps target field → source column. The name field is mapped separately using name_field. Omitting fields enables automatic mapping; an empty object means no mapping for other fields.

The coordinate system can be an EPSG code or local for a project-defined transformation. Conversion occurs during commit. Do not submit source coordinates in metres as WGS 84. CSV requires lat/lon, enlem/boylam, x/y or WKT columns.

The commit response includes ok, batch, created, by_type, skipped_geometry, invalid_geometry, invalid_attributes, missing_fields, unmapped, converted_units and field_map; endpoint-binding results are under uc. Rows with invalid geometry or attributes may be skipped; accepted rows are committed together. Do not assess success solely from ok. If no valid features remain, the response is 400.

Do not assume every target retains all source columns. Network feature imports store original fields in props.src; for reference targets, not all columns are copied when the source has 40 or more fields. Check fields required by your integration against representative records after confirmation.

Binding cable ends

For a cable group, uc_bagla options are etkin, tol_m, yakala and olustur. tol_m must be 0.1–5 metres. A source-mapped endpoint identifier takes precedence; nearby nodes are searched where appropriate. Ambiguous candidates are not selected automatically. A new endpoint type specified in olustur must be an appropriate node type enabled in the project.

Review bound, created, empty and ambiguous endpoint counts in uc. Visual proximity alone does not establish a technical fiber connection; cable endpoint relationships and fiber/port connections are separate records.

Reimporting with a source

1. Add kaynak: {"yeni": {"ad": "Örnek altyapı"}} and the selected anahtar_alani to the initial confirmation body. Obtain key candidates from the upload response's anahtar_adaylari list.
2. Read sources with GET /api/p/{pid}/kaynaklar. Upload the next file for the same source through the normal upload endpoint.
3. Send kaynak_id, crs, groups and, if needed, anahtar_alani to POST /api/p/{pid}/import/{token}/fark.
4. Review sayilar, ornekler, esleme_degisti and endpoint-binding results. Rows with changes across the old source, new source and local site values require a decision.
5. Send kaynak: {"id": 123}, hedef, kararlar and request_id in the confirmation request. Replace 123 with the actual source identifier.
6. Complete the default hedef: "dal" result through the design review/publication workflow; hedef: "dogrudan" requires appropriate administrator permission.

Decisions are assigned by category in kararlar.varsayilan and by source-row identifier in kararlar.satir. Use kaynak or yerel for source changes, conflicts and moves; use sil or birak for records missing from the source. Rows changed only locally are retained. Differences are recalculated from current data at confirmation; preview is not an immutable lock.

The source format and key field must match the existing source. Duplicate keys are rejected. Basemap-layer reimports cannot target a design branch; they are applied directly with appropriate permission. An ordinary reupload without a source record does not run this comparison.

Geometry import validation

The temporary file is deleted after successful geometry import. The confirmation endpoint supports optional request_id; retry the same token and body with the same identifier for the same user/project. The retry check occurs before reading the temporary file. Reuploading with a new identifier and automatically confirming can create duplicates; inspect the project and history first. If no retry record exists and the file is absent, the response is 404.

Importing a unit table

Unit import accepts CSV/TXT/TSV, JSON/GeoJSON and XLSX. Coordinates are optional. XLSX allows sheet selection; fields map to table columns such as source identifier, building and unit details.

1. Upload file to POST /api/p/{pid}/birim-aktarim; obtain token, columns and mapping suggestions.
2. Send kaynak, optional sayfa, alanlar, sabitler and durumlar to POST /api/p/{pid}/birim-aktarim/{token}/onizleme.
3. Review accepted, rejected, existing and changed source rows in the preview.
4. Add the preview's ozet and an 8–64-character request_id to the same body, then call POST /api/p/{pid}/birim-aktarim/{token}.
5. Cancel with DELETE /api/p/{pid}/birim-aktarim/{token}.

Preview is recalculated during confirmation. If the result changed, the server returns 409 with a new onizleme and writes no rows. A new request to import the same file, source and mapping is rejected because an active import already exists. Retrying with the same user, project, request_id, token and body returns the saved result; the retry check precedes file reading even if the successful import deleted its temporary file. Changed source rows do not silently overwrite existing evidence.

The table reader accepts files up to 50 MiB, 100,000 data rows, 200 columns and 500 characters per cell. Expanded XLSX content is limited to 300 MiB. Although the general upload gate is 300 MiB, a unit table over 50 MiB is rejected by the reader with 400; do not assume this is 413.

For project transfer, use Project bundle instead of these workflows.