Sări la conținutul principal

Date spațiale

Acest ghid explică cum să lucrezi cu forme geografice, coordonate și buffere în API Qarta.

Sistem de coordonate​

Toate coordonatele din Qarta trebuie să fie în format WGS84 (EPSG:4326):

  • Longitudine (Est-Vest): -180 la +180
  • Latitudine (Nord-Sud): -90 la +90
  • Format: [longitudine, latitudine] (nu [latitudine, longitudine])

Important: Observă ordinea: longitudine mai întâi, apoi latitudine. Aceasta este ordinea standard GeoJSON.

Exemple​

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]

Forme GeoJSON​

Qarta acceptă zone geografice ca obiecte GeoJSON Feature. Acestea definesc poligoane, puncte sau alte geometrii pentru interogări spațiale.

Formă poligon (cea mai frecventă)​

Utilizează un poligon pentru a defini o zonă de interes:

{
  "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": {}
}

Puncte cheie:

  • coordinates este o matrice de inele (inel exterior + orificii opționale)
  • Fiecare inel este o matrice de coordonate [longitudine, latitudine]
  • Prima și ultima coordonată trebuie să fie aceleași (închide poligonul)
  • Minim 4 coordonate per inel (3 puncte unice + 1 punct de închidere)

MultiPolygon (zone multiple)​

Definează zone multiple necontigue:

{
  "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": {}
}

Punct (locație singulară)​

Pentru un singur punct (utilizat cu punctele finale buffer):

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

Buffere​

Un buffer este o zonă circulară în jurul unuia sau mai multor puncte centrale. Formele buffer utilizează un format dedicat (nu GeoJSON standard) cu obiecte de coordonate {lat, long}.

Format formă buffer​

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

Proprietăți:

ProprietateTipObligatoriuDescriere
typeșirDaTip formă (de ex., "circle")
coordinatesmatrice de {lat, long}DaPuncte centrale pentru buffer
bufferStyleșirNuIndiciu stil vizual (de ex., "circle")

Matricea radiuses (distanțe în metri) este specificată separat la nivelul cererii, nu în interiorul obiectului formei.

Coordonatele buffer utilizează {lat, long} — nu ordinea GeoJSON

Formele buffer utilizează latitudine mai întâi în câmpurile de obiecte numite ({ "lat": ..., "long": ... }). Aceasta este diferită de coordonatele poligonului GeoJSON care utilizează ordinea matricei [longitudine, latitudine].

Exemple buffer​

Rază unică (1 milă):

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

Raze multiple (inele concentrice):

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

Utilizarea formelor în cererile API​

Puncte finale selecție​

Utilizează forme cu puncte finale "selecție" pentru a găsi date în o zonă:

{
  "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"]
}

Puncte finale buffer​

Utilizează forme buffer cu puncte finale "selecție-buffer":

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

Precizie coordonate​

Utilizează precizie corespunzătoare pentru cazul tău de utilizare:

PrecizieZecimaleAcuratețe
1.01~111 km
0.11~11 km
0.012~1.1 km
0.0013~111 m
0.00014~11 m
0.000015~1.1 m

Greșeli comune​

❌ Coordonate inversate​

// GREȘIT - latitudine mai întâi
"coordinates": [40.7128, -74.0060]

// CORECT - longitudine mai întâi
"coordinates": [-74.0060, 40.7128]

❌ Coordonată de închidere lipsă​

// GREȘIT - poligon nu este închis
"coordinates": [[[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300]]]

// CORECT - prima și ultima coordonate sunt aceleași
"coordinates": [[[-74.0200, 40.7000], [-74.0000, 40.7000], [-74.0000, 40.7300], [-74.0200, 40.7300], [-74.0200, 40.7000]]]

❌ Sistem de referință de coordonate greșit​

// GREȘIT - coordonate UTM
"coordinates": [475703, 4505727]

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

Instrumente pentru crearea formelor​

Web-based​

Programatic​

JavaScript/Leaflet:

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

Validare forme​

Înainte de a trimite forme la Qarta, validează-le:

Validator online: 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

Considerații de performanță​

  • Forme mai mici au performanță mai bună decât poligoane foarte mari
  • Fewer radiuses în buffere returnează rezultate mai repede
  • Coordonate precise nu afectează performanța (4-5 zecimale este bine)
  • Poligoanele complexe cu multe vârfuri pot fi mai lente

Mesaje de eroare​

"Invalid shape geometry"​

Cauză: GeoJSON malformat

Soluție:

  • Validează sintaxa JSON cu validator JSON
  • Verifică poligonul este închis (primul = ultima coordonată)
  • Verifică coordonatele sunt [longitudine, latitudine]

"403 Forbidden" pe parametrul shape​

Cauză: Interval de coordonate nevalid sau tip geometrie

Soluție:

  • Verifică coordonatele sunt în interval WGS84 (-180 la 180 longitudine, -90 la 90 latitudine)
  • Verifică utilizezi tip geometrie suportată (Polygon, MultiPolygon, Point)
  • Asigură-te că toate coordonatele interioare sunt matrice corect imbricată

Pași următori​