WFS — Web Feature Service

WFS (Web Feature Service) îți permite să recuperezi caracteristici geografice brute din straturile GeoServer. Folosește WFS pentru a descărca caracteristici ca GeoJSON, filtrează după criterii spațiale sau de atribute, și integrează datele de caracteristici în aplicațiile tale.

Toate cererile merg la: https://graph.quarticle.ro/graph/layers/wfs/

Autentificare: Adaugă antetul Authorization: YOUR_API_KEY la toate cererile.

GetFeature

Recuperează caracteristici geografice dintr-un strat WFS.

Parametri obligatori

Parametru	Descriere	Exemplu
`service`	`WFS`	`WFS`
`version`	Versiune WFS	`2.0.0`
`request`	`GetFeature`	`GetFeature`
`typeNames`	Nume strat(e)	`GRAPHRASTER:light_pollution`

Parametri opționali

Filtrare

Parametru	Descriere	Exemplu
`featureID`	Returnează doar caracteristici cu ID specific	`namespace:layername.id`
`bbox`	Filtru spațial: `minx,miny,maxx,maxy,SRS`	`2554219.59,5763351.78,2554220.89,5763352.09,EPSG:3857`
`cql_filter`	Expresie filtru GeoServer CQL	`population > 1000000`
`filter`	XML Filtru OGC	(vezi exemple mai jos)

Control ieșire

Parametru	Descriere	Exemplu
`outputFormat`	Format de răspuns	`application/json` (GeoJSON)
`srsName`	Sistem de coordonate de ieșire	`EPSG:4326`
`propertyName`	Proprietăți separate prin virgulă de returnat	`name,population,area`

Paginare

Parametru	Descriere	Exemplu
`count` (WFS 2.0.0)	Max caracteristici de returnat	`100`
`maxFeatures` (WFS 1.1.0)	Max caracteristici de returnat	`100`
`startIndex`	Decalaj paginare	`200`

Sortare

Parametru	Descriere	Exemplu
`sortBy`	Sortează rezultate după câmp	`population D` (descrescător) sau `population A` (crescător)

Exemple

Interogare de caracteristici de bază

cURL
JavaScript
Python

curl -X GET "https://graph.quarticle.ro/graph/layers/wfs/GetFeature" \
  -H "Authorization: YOUR_API_KEY" \
  --data-urlencode "service=WFS" \
  --data-urlencode "version=2.0.0" \
  --data-urlencode "request=GetFeature" \
  --data-urlencode "typeNames=GRAPHRASTER:light_pollution" \
  --data-urlencode "outputFormat=application/json"

const apiKey = process.env.QARTA_API_KEY;

const params = new URLSearchParams({
  service: 'WFS',
  version: '2.0.0',
  request: 'GetFeature',
  typeNames: 'GRAPHRASTER:light_pollution',
  outputFormat: 'application/json'
});

fetch(`https://graph.quarticle.ro/graph/layers/wfs/GetFeature?${params}`, {
  headers: { 'Authorization': `${apiKey}` }
})
  .then(r => r.json())
  .then(geojson => {
    console.log(`Retrieved ${geojson.features.length} features`);
    geojson.features.forEach(f => {
      console.log(f.properties);
    });
  });

import requests
import json

api_key = os.getenv('QARTA_API_KEY')

response = requests.get(
  'https://graph.quarticle.ro/graph/layers/wfs/GetFeature',
  params={
    'service': 'WFS',
    'version': '2.0.0',
    'request': 'GetFeature',
    'typeNames': 'GRAPHRASTER:light_pollution',
    'outputFormat': 'application/json'
  },
  headers={'Authorization': f'{api_key}'}
)

geojson = response.json()
print(f'Retrieved {len(geojson["features"])} features')

Filtru spațial (BBox)

Interogează caracteristici într-o cutie de delimitare:

cURL

curl -X GET "https://graph.quarticle.ro/graph/layers/wfs/GetFeature" \
  -H "Authorization: YOUR_API_KEY" \
  --data-urlencode "service=WFS" \
  --data-urlencode "version=2.0.0" \
  --data-urlencode "request=GetFeature" \
  --data-urlencode "typeNames=GRAPHRASTER:cities" \
  --data-urlencode "bbox=-74.1,40.6,-73.9,40.8,EPSG:4326" \
  --data-urlencode "outputFormat=application/json"

Filtru CQL (Interogare atribute)

Filtrează caracteristici după atribute folosind CQL (Common Query Language):

Filtru simplu
Condiții combinate
CQL spațial
Exemplu cURL

# Obține orașe cu populație > 1 milion
cql_filter=population > 1000000

# Zone urbane cu populație > 500k
cql_filter=type = 'urban' AND population > 500000

# Caracteristici în cadrul unui punct specific (buffer)
cql_filter=DWITHIN(geom, POINT(-74.0060 40.7128), 1000, meters)

# Caracteristici care conțin un punct
cql_filter=CONTAINS(geom, POINT(-74.0060 40.7128))

# Caracteristici intersectând un poligon
cql_filter=INTERSECTS(geom, POLYGON((-74.1 40.6, -73.9 40.6, -73.9 40.8, -74.1 40.8, -74.1 40.6)))

curl -X GET "https://graph.quarticle.ro/graph/layers/wfs/GetFeature" \
  -H "Authorization: YOUR_API_KEY" \
  --data-urlencode "service=WFS" \
  --data-urlencode "version=2.0.0" \
  --data-urlencode "request=GetFeature" \
  --data-urlencode "typeNames=GRAPHRASTER:cities" \
  --data-urlencode "cql_filter=population > 1000000 AND country = 'USA'" \
  --data-urlencode "outputFormat=application/json"

Selecție și paginare proprietăți

Recuperează proprietăți specifice și pagineaza prin seturi mari de rezultate:

cURL
JavaScript

curl -X GET "https://graph.quarticle.ro/graph/layers/wfs/GetFeature" \
  -H "Authorization: YOUR_API_KEY" \
  --data-urlencode "service=WFS" \
  --data-urlencode "version=2.0.0" \
  --data-urlencode "request=GetFeature" \
  --data-urlencode "typeNames=GRAPHRASTER:cities" \
  --data-urlencode "propertyName=name,population,country" \
  --data-urlencode "count=100" \
  --data-urlencode "startIndex=0" \
  --data-urlencode "sortBy=population D" \
  --data-urlencode "outputFormat=application/json"

async function getAllFeatures(typeName) {
  const apiKey = process.env.QARTA_API_KEY;
  const pageSize = 100;
  let allFeatures = [];
  let page = 0;

  while (true) {
    const params = new URLSearchParams({
      service: 'WFS',
      version: '2.0.0',
      request: 'GetFeature',
      typeNames: typeName,
      count: pageSize.toString(),
      startIndex: (page * pageSize).toString(),
      outputFormat: 'application/json'
    });

    const response = await fetch(
      `https://graph.quarticle.ro/graph/layers/wfs/GetFeature?${params}`,
      { headers: { 'Authorization': `${apiKey}` } }
    );

    const geojson = await response.json();
    allFeatures.push(...geojson.features);

    // Stop if fewer features than page size
    if (geojson.features.length < pageSize) break;
    page++;
  }

  return allFeatures;
}

Formate de ieșire

WFS poate returna caracteristici în mai multe formate:

Format	MIME Type	Caz de utilizare
GeoJSON	`application/json`	Recomandat pentru aplicații web
GML 3	`text/xml` sau `application/gml+xml`	Standard OGC, aplicații desktop GIS
CSV	`text/csv`	Analiză date, export Excel

Exemplu:

outputFormat=application/json    # GeoJSON
outputFormat=application/gml+xml # GML
outputFormat=text/csv            # CSV

Structura răspunsului (GeoJSON)

Un răspuns WFS tipic în format GeoJSON:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "cities.1",
      "geometry": {
        "type": "Point",
        "coordinates": [-74.0060, 40.7128]
      },
      "properties": {
        "name": "New York",
        "population": 8335897,
        "country": "USA"
      }
    },
    {
      "type": "Feature",
      "id": "cities.2",
      "geometry": {
        "type": "Point",
        "coordinates": [-87.6298, 41.8857]
      },
      "properties": {
        "name": "Chicago",
        "population": 2693976,
        "country": "USA"
      }
    }
  ]
}

Gestionarea erorilor

Dacă o cerere GetFeature eșuează, eroarea este returnată ca XML în mod implicit:

<?xml version="1.0" encoding="UTF-8"?>
<ExceptionReport version="2.0.0">
  <Exception exceptionCode="InvalidParameterValue">
    <ExceptionText>
      Unknown typename: invalid_layer
    </ExceptionText>
  </Exception>
</ExceptionReport>

Sau ca JSON dacă adaugi &outputFormat=application/json:

{
  "code": "InvalidParameterValue",
  "message": "Unknown typename: invalid_layer"
}

Erori comune:

InvalidParameterValue: typeNames greșit, srsName sau outputFormat
NoApplicableCode: Eroare sintaxă filtru CQL sau nume proprietate nevalid
Unauthorized: Cheia API lipsă sau nevalidă
ServiceException: Eroare generală GeoServer (verifică parametrii)

Sfaturi și bune practici

Utilizează JSON pentru aplicații web: outputFormat=application/json este cel mai ușor de parsetat în JavaScript
Filtrează devreme: Utilizează bbox sau cql_filter pentru a reduce sarcina în loc să descarci toate caracteristicile
Selectează proprietăți: Solicitează doar câmpurile de care ai nevoie cu propertyName=field1,field2
Pagineaza seturi mari: Utilizează count și startIndex pentru a evita timeout-urile
Sistem de coordonate: Datele în EPSG:4326 (lat/lon) sunt standard; utilizează srsName pentru a transforma dacă este necesar
Cache rezultate: Pentru seturi de date accesate frecvent, luați în considerare stocarea în cache a datelor caracteristicilor local

Pași următori

Prezentare generală GeoServer
Ghid WMS — Redă plăci de hartă
Caz de utilizare interogare caracteristici — Exemple de interogare caracteristici din lumea reală

GetFeature​

Parametri obligatori​

Parametri opționali​

Filtrare​

Control ieșire​

Paginare​

Sortare​

Exemple​

Interogare de caracteristici de bază​

Filtru spațial (BBox)​

Filtru CQL (Interogare atribute)​

Selecție și paginare proprietăți​

Formate de ieșire​

Structura răspunsului (GeoJSON)​

Gestionarea erorilor​

Sfaturi și bune practici​

Pași următori​