GeospatialCoordinates (Semantic Module)

← Back to Modules Reference

The GeospatialCoordinates semantic module manages latitude and longitude positions, GPS waypoints, and spatial locations (such as store finders, delivery tracking, or asset mapping).

Beyond simple coordinate storage, tagging a property with GeospatialCoordinates integrates with native PostGIS spatial indexing. This allows your backend to execute lightning-fast proximity and radius queries (e.g., “Find all stores within 5 miles” or “Find drivers nearest to this pickup”) while automatically translating coordinates between client-friendly formats (like "lat,lon" or GeoJSON) and spatial database geometry.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a String or JSON property)
Data Types	String (for delimited or WKT strings) or JSON (for GeoJSON objects)
Default Format	'lat,lon' (e.g., "37.7749,-122.4194")
Spatial Reference System (SRS)	WGS84 (EPSG:4326 standard GPS datum)
Coordinate Precision	6 decimal places (accuracy to ~11 centimeters)
PostGIS Integration	Enabled by default with automated spatial indexing

---

Key Capabilities

1. Multi-Format Coordinate Support (format)

Clients can interact with geospatial data using their preferred format. The Serverless Engine handles parsing and formatting automatically:

• 'lat,lon' (Default): Comma-separated string with latitude first, then longitude (e.g. "37.7749,-122.4194").
• 'lon,lat': Comma-separated string with longitude first (e.g. "-122.4194,37.7749").
• 'geojson': Standard RFC 7946 GeoJSON Point geometry:

  {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  }

• 'wkt' / 'postgis': OpenGIS Well-Known Text representation (e.g. "POINT(-122.4194 37.7749)").
• 'degree': Human-readable cardinal degrees (e.g. "37.7749°N, 122.4194°W").

2. Native Spatial Indexing & Proximity Queries

• Automated Axis Translation: GIS databases natively expect $(X, Y)$ order (Longitude, Latitude). The engine handles this axis mapping transparently so client developers don’t have to remember coordinate ordering.
• Spatial Indexing: Automatically indexes coordinates using R-Tree spatial indices, enabling high-performance radius queries (within, near, distance).

3. Boundary & Range Validation (enableValidation)

• Checks that coordinates fall within valid geographic boundaries: Latitude between $-90.0^\circ$ and $+90.0^\circ$, and Longitude between $-180.0^\circ$ and $+180.0^\circ$.
• Custom bounding boxes can be configured via validationBounds to restrict pins to a specific city or operational service territory.

---

Configuration Options

When configuring the GeospatialCoordinates semantic in the Domain Modeler, you can customize:

Option	Type	Default	Description
format	'lat,lon' | 'lon,lat' | 'geojson' | 'wkt' | 'degree'	'lat,lon'	Coordinate format for API requests and responses.
spatialReferenceSystem	'EPSG:4326' | 'EPSG:3857'	'EPSG:4326'	Spatial Reference System (WGS84 GPS standard).
coordinatePrecision	number	6	Number of decimal places returned in API responses.
enableValidation	boolean	true	Validates latitude ($-90$ to $90$) and longitude ($-180$ to $180$).
enableSpatialIndexing	boolean	true	Creates native PostGIS spatial indexes for proximity queries.
includeElevation	boolean	false	Enables 3D points with vertical elevation ($Z$ coordinate).

---

API Lifecycle Examples

1. Storing Coordinates with Default Format ('lat,lon')

A client creates a store location passing standard "lat,lon" text:

POST /stores
Content-Type: application/json

{
  "name": "Downtown Hub",
  "location": "37.774929, -122.419418"
}

Server Response (201 Created):

{
  "data": {
    "id": "store_101",
    "name": "Downtown Hub",
    "location": "37.774929,-122.419418"
  }
}

---

2. Using GeoJSON Point Format

When format: "geojson" is configured:

POST /deliveries
Content-Type: application/json

{
  "orderId": "ord_882",
  "dropoffLocation": {
    "type": "Point",
    "coordinates": [-73.985131, 40.748817]
  }
}

Server Response (201 Created):

{
  "data": {
    "id": "deliv_401",
    "orderId": "ord_882",
    "dropoffLocation": {
      "type": "Point",
      "coordinates": [-73.985131, 40.748817]
    }
  }
}

---

3. Validation Failure (Out of Bounds)

A client sends latitude exceeding $90^\circ$:

{
  "location": "95.5000, -120.0000"
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Coordinates [95.5, -120] are out of validation bounds."
}

---

Validation Rules & Modeling Guidelines

• Applicable Property Types: Apply to a String property (for delimited strings, WKT, or degrees) or a JSON property (for GeoJSON objects).
• Length Constraints: For String properties, the default Maximum Length of 255 characters easily accommodates coordinate strings and WKT text.