Overview

Understand the application architecture and the current integration API contract.

Last updated: 10 November 2026

Architecture

SoSoMaps is a single application with a browser interface and a Python-based FastAPI server. Persistent data is stored in PostgreSQL; geometries and spatial operations use PostGIS. The browser connects to the server through JSON requests over HTTP. Uploads use multipart/form-data; downloads use the relevant file content type.

Every project belongs to an organisation. The project API checks the session user's organisation and role. A client-supplied organisation header cannot change that boundary. Map geometries are stored in WGS 84 coordinates; attributes and some technical records use JSON fields.

Current API contract

The browser application uses cookie-authenticated /api endpoints. For external integrations, the v1 API under /api/v1 authenticates with an access key. X-GIS-API-Surum: 1 identifies the API version and X-GIS-Surum the application version. /api/v1/openapi.json and /api/v1/docs provide public schema and usage documentation; the default Swagger and ReDoc endpoints are not exposed.

These documents describe the current HTTP contract used by the application. Cookie-authenticated API errors do not all share one format; v1 errors use a detail, kod, alan envelope. Read the available catalogue, session and project scope from the server.

Initial read workflow

1. Prepare an access key with the appropriate scope using Authentication.
2. Call GET /api/v1/me to read the key owner's identity and scope.
3. Call GET /api/v1/projects to list accessible projects.
4. Call GET /api/v1/projects/{pid}/features to obtain visible map data; retain pagination and change cursors.
5. Follow Your first API request to complete reading, writing and change tracking.

{pid} is the numeric project identifier returned by the server. When using cookie-authenticated application endpoints, also follow the authentication workflows in Editing API and Import API.

Client generation and downloads

No official SDK has been published for SoSoMaps. Download the v1 OpenAPI file to generate your own client, or import the Postman collection.

Based on the OpenAPI Generator usage documentation and Python generator documentation, the following command can be used where the tool is installed:

openapi-generator-cli generate -i sosomaps-v1.openapi.json -g python -o sosomaps-istemci

This command generates local client files. Configure your base URL and Authorization: Bearer header; interpret responses left as generic objects in the schema using the field descriptions in the v1 reference. Validate the generated client against your target installation; this example is not an SDK acceptance test.

Modules and product scope

The core and shared site modules are always enabled. Address and building, and fiber modules are available according to organisation, project and licence scope. Electric infrastructure is disabled by default and is Coming soon. Electric definitions in the catalogue do not grant general access to that module.

The product covers mapping, physical infrastructure, fiber connections, building and endpoint records, technical circuits and engineering outputs. CRM, billing, NOC/alarm, general ticketing and SCADA functions are outside its scope. The customer technical key denotes an address entry, not a commercial customer record.

The interface is in Turkish. Offline field packages, office review, design approval and controlled publication are within the product scope. Use webhooks for project events and OGC services for external map and feature reading.