SQL

Til at begynde med, en hurtig beskrivelse af hvad SQL API er: Postgresql med PostGIS udvidelsen (som er kernen i GC2) er nogle af de mest kraftfulde stykker software inden for kortlægning og GIS. Det er svært at forestille sig en rumlig vektoranalyse, der ikke kan lade sig gøre i en PostGIS-database. Men PostGIS er et stykke serversoftware, der kræver nogle tekniske færdigheder til at installere og bruge. Det handler ikke kun om at køre SQL'er, men du skal også vide, hvordan du formaterer og viser resultatet. SQL API giver dig mulighed for at forespørge GC2's PostGIS database ved at sende SQL-strengen via HTTP/HTTPS og modtage resultatet formateret som GeoJSON klar til visning på et webkort eller som Excel/CSV

Signaturen for SQL API er som følger:

https://example.com/api/v2/sql/[database]

Eller hvis der benyttes en sub-user:

https://example.com/api/v2/sql/[subuser@database]

SQL-strengen og yderligere parametere kan enten sendes som URL parametere eller i en JSON body. Følgende eksempler bruger programmet cURL, men enhver HTTP klient kan bruges.

URL parameter. Bemærk at SQL-stregen er URL encoded: 

curl -i --header "Content-Type: application/x-www-form-urlencoded" -XGET \
https://gc2.io/api/v2/sql/dk\
?q=SELECT%201

JSON body. Body'en kan sendes som både GET og POST. Det sidste kan bruges i klienter, som ikke kan GET med body. Fx webbrowsere:

curl -i --header "Content-Type: application/json" -X GET \
https://gc2.io/api/v2/sql/dk --data \
'{"q":"SELECT 1"}'

Som standard returneres resultatet som GeoJSON. Men MS Excel og CSV er også en mulighed. Hvis Excel eller CSV vælges, kan man få geometrierne med ud som enten GeoJSON eller WKT strenge i en kolonne. Hvis "geoformat" ikke sættes, returneres der ikke geometrier.

Resultatets geometrier returneres som standard i EPSG:3857 (Web mercator), selvom kilden har en anden projektion. Man kan vælge resultatets projektion med "srs":

curl -i --header "Content-Type: application/json" -X GET \
https://gc2.io/api/v2/sql/dk --data \
'{
  "q":"SELECT 1 as id,ST_setsrid(ST_MakePoint(10,56),4326) as geom",
  "srs":"25832",
  "format":"csv",
  "geoformat":"wkt",
  "allstr": "1",
  "lifetime": 0,
  "base64": 0 
}'

Følgende parametre kan bruges:

q: SQL streng (obligatorisk)
srs: EPSG koden som resultatet skal være i (Standard: 3857)
format: geojson, excel eller csv (standard geojson)
geoformat: geojson eller wkt. Vedr. kun Excel og CSV (Standard: ikke sat)
allstr: Alle kolonner sættes som tekst-type (Standard: ikke sat)
lifetime: Cache resultatet i dette antal sekunder på serveren (Standard: 0)
base64: Markerer at SQL strengen er base64 kodet. Kan bruges til at "snyde" firewalls med "threat detection" (Standard: ikke sat)
key: Brugerens API nøgle. Skal bruges hvis læsning af en eller flere relationer er sikret.

INSERT, UPDATE og DELETE

Man kan ændre data ved INSERT, UPDATE og DELETE.  SQL API vil returnere antal af række, som er blevet påvirket af transaktionen.

--data '{
  "q":"DELETE FROM foo.bar",
  "key":"1fa446367cb64e14318427f5f17a0ecf"
}'

Bulk API

Bulk API'et giver dig mulighed for at POST flere transaktioner, som vil blive kørt i samme transaktionsblok. Bulk API'et kræver GC2 API-nøglen i header, og indholdstypen skal indstilles til text/plain. SQLer skal være nye linjeseparerede.

curl -i \
  --header "Content-Type: text/plain" \
  --header "GC2-API-KEY: abc123" \
  -X POST http://host.com/api/v2/sql/dk --data \
'
INSERT INTO my_table (id) VALUES(1)
INSERT INTO my_table (id) VALUES(2)
INSERT INTO my_table (id) VALUES(3)
INSERT INTO my_table (id) VALUES(4)
'

0 Comments

Add your comment

E-Mail me when someone replies to this comment