Qarta API (Layers API)

Prezentare generală

Qarta este platforma de inteligență geospațială a Quarticle, oferind API-uri pentru analize bazate pe locație, raportare de portofolii și evaluare a riscurilor. API-ul Layers oferă dezvoltatorilor acces programatic la capabilități geospațiale puternice, inclusiv geocodare, analiză spațială, raportare de riscuri și îmbogățire de puncte.

Capacități cheie

Qarta oferă șase zone de capabilități esențiale:

📍 Servicii de locație

• Geocodare - Convertiți adresele în coordonate geografice (latitudine/longitudine)
• Geocodare inversă - Convertiți coordonatele în adrese lizibile
• Completare automată de locuri - Sugestii de căutare pentru interogări de adrese

📊 Analiza portofoliului

• Selecție de puncte - Recuperați date de puncte într-o formă geografică (poligoane)
• Selecție de buffer - Recuperați date în zone de buffer circular în jurul unei locații
• Selecție de intrări - Recuperați date detaliate de intrări/înregistrări cu filtrare spațială
• Rapoarte de acumulare - Agregați și rezumați date după coloane în arii geografice

⚠️ Raportare de riscuri

• Risc punct - Generați PDF-uri/HTML-uri detaliate de evaluare a riscurilor pentru o locație specifică
• Risc punct-buffer - Generați rapoarte de riscuri cu date acumulate în zone de buffer

🔍 Îmbogățire de puncte

• Îmbogățire punct unic - Îmbogățiți un punct cu date din straturi geospațiale
• Îmbogățire în lot - Îmbogățiți mai multe puncte într-o singură cerere cu informații de straturi

🗺️ Servicii web (WMS/WFS)

• Web Map Service (WMS) - Stream dale de hartă, legende și informații de caracteristici
• Web Feature Service (WFS) - Interogați caracteristici geografice folosind standarde OGC
• 👉 Ghid servicii web GeoServer

📡 Evenimente live

• Îmbogățire de evenimente live - Procesați și îmbogățiți date de evenimente live cu filtre de geogarnitură

URL de bază API

https://graph.quarticle.ro

Autentificare

Toate punctele finale necesită autentificare cu cheie API prin antetul Authorization:

Authorization: YOUR_API_KEY

Consultați Ghidul de autentificare pentru instrucțiuni de configurare.

Versiuni API

Qarta acceptă două versiuni API:

Versiune	Descriere	Model de filtru
V1	API original cu filtre simple	{field, value}
V2	API îmbunătățit cu filtre imbricate/recursive	Arbori de filtru recursivi

V2 introduce un model de filtru mai puternic care acceptă condiții imbricate. Consultați Ghidul V1 vs V2 pentru detalii de migrare.

Formate de ieșire

Diferitele puncte finale acceptă formate de ieșire diverse:

• JSON - Format de răspuns implicit (application/json)
• CSV - Export de date tabulare prin antetul Accept: text/csv (puncte/intrări)
• PDF - Rapoarte de riscuri în format PDF
• HTML - Rapoarte de riscuri ca documente HTML
• PNG - Imagini de hartă și grafică de legende (WMS)
• XML - Documente de capabilități WMS/WFS
• GeoJSON - Caracteristici geografice (format nativ pentru intrări de forme)

Concepte esențiale

Forme geografice

Qarta acceptă forme geografice ca caracteristici GeoJSON:

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[[lon, lat], [lon, lat], ...]]
  },
  "properties": {}
}

Toate coordonatele trebuie să fie în format WGS84 (EPSG:4326): [longitudine, latitudine].

Buffere

Zonele de buffer sunt arii circulare în jurul unui punct. Specificați prin:

{
  "type": "Point",
  "coordinates": [lon, lat],
  "radiuses": [1000, 5000, 10000]  // meters
}

Filtre

Filtrele reduc rezultatele pe baza atributelor de date:

Format V1:

[
  {"field": "oe_id", "value": "someValue"},
  {"field": "property_type", "value": "residential"}
]

Format V2 (imbricat):

[
  {
    "field": "oe_id",
    "value": "someValue",
    "filters": [
      {"field": "property_type", "value": "residential"}
    ]
  }
]

Parametrul source

Majoritatea punctelor finale de portofoliu necesită un parametru source care identifică care strat de date să se interogeze. O sursă reprezintă un set de date provizionat în contul dvs — de exemplu, un portofoliu de asigurări specific, catalog de proprietăți sau set de date de riscuri.

• Fiecare cont poate avea una sau mai multe surse aprovizionate
• Valoarea sursei este un identificator șir (de ex., "portfolio_01")
• Pentru a descoperi sursele disponibile și configurația acestora, apelați punctul final Provision:

curl -X GET "https://graph.quarticle.ro/graph/api/v1/reports/portfolio/provision" \
  -H "Authorization: YOUR_API_KEY"

Răspunsul conține un obiect provisioning cheiat după numele sursei, cu fiecare sursă listând coloanele disponibile, filtre, configurație de puncte și capacități de raportare:

{
  "provisioning": {
    "portfolio_01": {
      "columns": [
        { "field": "insured_value", "type": "number" },
        { "field": "property_type", "type": "string" }
      ],
      "filters": [
        { "field": "oe_id", "label": "Organization", "required": true, "values": ["org_1", "org_2"] }
      ],
      "reports": {
        "accumulation": { "enabled": true }
      }
    }
  }
}

Utilizați numele sursei ca parametru source în toate apelurile API de portofoliu, intrări și puncte ulterioare.

Linkuri rapide

• Primii pași - Autentificați-vă și efectuați primul apel API
• Ghid V1 vs V2 - Înțelegeți diferențele dintre versiuni API
• Ghid export CSV - Cum să descărcați date ca CSV
• Ghid date spațiale - Lucru cu GeoJSON și coordonate
• Servicii web GeoServer - WMS și WFS conforme cu OGC
• Python SDK - Client Python complet tipizat care acoperă toate punctele finale
• Colecția Postman - Cereri pre-configurate pentru testarea tuturor punctelor finale
• Cazuri de utilizare - Exemple de integrare din lumea reală

Cazuri de utilizare

Modele de integrare obișnuite

Evaluare de riscuri

1. Obțineți factori de riscuri pentru proprietăți folosind punctul final de risc
2. Generați rapoarte PDF detaliate pentru prezentări client

Analiza portofoliului

1. Definiți arii de interes geografic
2. Interogați puncte sau intrări în acele arii
3. Acumulați metrici cheie (număr, sumă, medie)
4. Exportați rezultatele ca CSV pentru raportare

Inteligență de locație

1. Acceptați adrese de utilizator via completare automată
2. Geocodificați la coordonate
3. Îmbogățiți cu date din straturile de mediu
4. Recuperați perspective relevante

Îmbogățire de date

1. Încărcați lot de locații
2. Îmbogățiți punctele cu date din straturi
3. Agregați metrici de riscuri
4. Exportați ca CSV

Consultați secțiunea Cazuri de utilizare pentru exemple detaliate ale fiecărui model.

Gestionare erori

Toate erorile returnează un format JSON consecvent:

{
  "errorMessage": {
    "message": "Description of what went wrong"
  }
}

Coduri de stare HTTP obișnuite:

• 400 - Cerere proastă (parametri nevalizi)
• 401 - Neautorizat (cheie API lipsă/invalidă)
• 403 - Interzis (probleme cu parametrul shape)
• 500 - Eroare server (problemă internă)

Consultați Ghidul de erori pentru informații detaliate de erori.

Suport

• Colecția Postman - Documentație interactivă pentru toate cele 36 de puncte finale
• GitHub Issues - Raportați erori și solicitați caracteristici
• Contactați suportul - Obțineți ajutor de la echipa noastră

Pașii următori

1. Porniți - Configurați autentificarea și efectuați primul apel
2. Explorați cazurile de utilizare - Vedeți exemple practice ale fluxurilor obișnuite
3. Descărcați colecția Postman - Testați punctele finale în Postman
4. Revizuiți colecția Postman - Răsfoiți toate cele 36 de puncte finale cu documentație detaliată