Spatial Data

This guide explains how to work with geographic shapes, coordinates, and buffers in Qarta API.

Coordinate System

All coordinates in Qarta must be in WGS84 (EPSG:4326) format:

• Longitude (East-West): -180 to +180
• Latitude (North-South): -90 to +90
• Format: [longitude, latitude] (not [latitude, longitude])

Important: Notice the order: longitude first, then latitude. This is the standard GeoJSON order.

Examples

New York City:        [-74.0060, 40.7128]
London, UK:           [-0.1278, 51.5074]
Tokyo, Japan:         [139.6917, 35.6895]
Sydney, Australia:    [151.2093, -33.8688]

GeoJSON Shapes

Qarta accepts geographic areas as GeoJSON Feature objects. These define polygons, points, or other geometries for spatial queries.

Polygon Shape (Most Common)

Use a polygon to define an area of interest:

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-74.0200, 40.7000],
        [-74.0000, 40.7000],
        [-74.0000, 40.7300],
        [-74.0200, 40.7300],
        [-74.0200, 40.7000]
      ]
    ]
  },
  "properties": {}
}

Key points:

• coordinates is an array of rings (outer ring + optional holes)
• Each ring is an array of [longitude, latitude] coordinates
• The first and last coordinate must be the same (closes the polygon)
• Minimum 4 coordinates per ring (3 unique points + 1 closing point)

MultiPolygon (Multiple Areas)

Define multiple non-contiguous areas:

{
  "type": "Feature",
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300], [-74.0200, 40.7000]]
      ],
      [
        [[-73.9000, 40.7000], [-73.8800, 40.7000], [-73.8800, 40.7200], [-73.9000, 40.7200], [-73.9000, 40.7000]]
      ]
    ]
  },
  "properties": {}
}

Point (Single Location)

For a single point (used with buffer endpoints):

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-74.0060, 40.7128]
  },
  "properties": {}
}

Buffers

A buffer is a circular zone around one or more center points. Buffer shapes use a dedicated format (not standard GeoJSON) with {lat, long} coordinate objects.

Buffer Shape Format

{
  "type": "circle",
  "coordinates": [
    { "lat": 40.7128, "long": -74.0060 }
  ],
  "bufferStyle": "circle"
}

Properties:

Property	Type	Required	Description
type	string	Yes	Shape type (e.g., "circle")
coordinates	array of {lat, long}	Yes	Center point(s) for the buffer
bufferStyle	string	No	Visual style hint (e.g., "circle")

The radiuses array (distances in meters) is specified separately at the request level, not inside the shape object.

Buffer coordinates use {lat, long} — not GeoJSON order

Buffer shapes use latitude first in named object fields ({ "lat": ..., "long": ... }). This is different from GeoJSON polygon coordinates which use [longitude, latitude] array order.

Buffer Examples

Single radius (1 mile):

{
  "shape": {
    "type": "circle",
    "coordinates": [{ "lat": 40.7128, "long": -74.0060 }]
  },
  "radiuses": [1609]
}

Multiple radii (concentric rings):

{
  "shape": {
    "type": "circle",
    "coordinates": [{ "lat": 40.7128, "long": -74.0060 }]
  },
  "radiuses": [1000, 5000, 10000, 20000]
}

Using Shapes in API Requests

Selection Endpoints

Use shapes with "selection" endpoints to find data within an area:

{
  "source": "portfolio_01",
  "shape": {
    "type": "Feature",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300], [-74.0200, 40.7000]]]
    },
    "properties": {}
  },
  "filters": [{"field": "property_type", "value": "residential"}],
  "properties": ["name", "value"]
}

Buffer Endpoints

Use buffer shapes with "buffer-selection" endpoints:

{
  "source": "portfolio_01",
  "shape": {
    "type": "circle",
    "coordinates": [{ "lat": 40.7128, "long": -74.0060 }]
  },
  "radiuses": [1000, 5000],
  "filters": [{"field": "property_type", "value": "residential"}]
}

Coordinate Precision

Use appropriate precision for your use case:

Precision	Decimal Places	Accuracy
1.0	1	~111 km
0.1	1	~11 km
0.01	2	~1.1 km
0.001	3	~111 m
0.0001	4	~11 m
0.00001	5	~1.1 m

Example:

// High precision (centimeter level) - usually unnecessary
[-74.006012345, 40.712834567]

// Medium precision (meter level) - good for most uses
[-74.00601, 40.71283]

// Low precision (kilometer level) - for broad areas
[-74.01, 40.71]

Common Mistakes

❌ Reversed Coordinates

// WRONG - latitude first
"coordinates": [40.7128, -74.0060]

// CORRECT - longitude first
"coordinates": [-74.0060, 40.7128]

❌ Missing Closing Coordinate

// WRONG - polygon not closed
"coordinates": [[[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300]]]

// CORRECT - first and last coordinates are the same
"coordinates": [[[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300], [-74.0200, 40.7000]]]

❌ Wrong Coordinate Reference System

// WRONG - UTM coordinates
"coordinates": [475703, 4505727]

// CORRECT - WGS84/EPSG:4326
"coordinates": [-74.0060, 40.7128]

Tools for Creating Shapes

Web-Based

• Mapbox Draw (https://mapbox.com/mapbox-gl-draw/) - Create shapes on a map
• GeoJSON.io (https://geojson.io/) - Visual GeoJSON editor
• Google Maps - Draw shapes, export as coordinates

Programmatic

JavaScript/Leaflet:

const shape = {
  type: "Feature",
  geometry: {
    type: "Polygon",
    coordinates: [[[lng1, lat1], [lng2, lat2], [lng3, lat3], [lng1, lat1]]]
  },
  properties: {}
};

Python:

from shapely.geometry import Point, Polygon
import json

# Create polygon from coordinates
coords = [(-74.0200, 40.7000), (-74.0000, 40.7000), (-74.0000, 40.7300), (-74.0200, 40.7300)]
polygon = Polygon(coords)

# Convert to GeoJSON
geojson = {
    "type": "Feature",
    "geometry": json.loads(polygon.geom_type, ...),
    "properties": {}
}

Validating Shapes

Before sending shapes to Qarta, validate them:

Online validator: https://geojson.io/

Python:

from shapely.geometry import shape

def is_valid_geojson(feature):
    try:
        geom = shape(feature['geometry'])
        return geom.is_valid
    except:
        return False

JavaScript:

function isValidGeoJSON(feature) {
  try {
    if (!feature.geometry || !feature.geometry.coordinates) return false;
    if (!Array.isArray(feature.geometry.coordinates)) return false;
    return true;
  } catch {
    return false;
  }
}

Performance Considerations

• Smaller shapes perform better than very large polygons
• Fewer radiuses in buffers return results faster
• Precise coordinates don't impact performance (4-5 decimal places is fine)
• Complex polygons with many vertices may be slower

Error Messages

"Invalid shape geometry"

Cause: Malformed GeoJSON

Solution:

• Validate JSON syntax with a JSON validator
• Check polygon is closed (first = last coordinate)
• Verify coordinates are [longitude, latitude]

"403 Forbidden" on shape parameter

Cause: Invalid coordinate range or geometry type

Solution:

• Verify coordinates are in WGS84 range (-180 to 180 longitude, -90 to 90 latitude)
• Check that you're using a supported geometry type (Polygon, MultiPolygon, Point)
• Ensure all inner coordinates are properly nested arrays

Next Steps

• CSV Export Guide - Export results as CSV
• V1 vs V2 Guide - Understanding filter differences
• Use Cases - Real-world examples with shapes
• Postman Collection - Browse all endpoints