Using the API

Geo Data Connector exposes a REST API that mirrors everything available in the web UI. Use it to automate workflows, integrate with other systems, or connect an AI coding assistant to drive the full discover-subscribe-download flow programmatically.

The API is authenticated with a Personal Access Token (PAT). Everything you can do in the UI, you can do via the API (with a few intentional exceptions).

The complete endpoint reference — request/response shapes, parameters, error codes, and a worked example — is in the API Reference.

Authentication

Create a PAT in the web UI: Settings → Personal Access Tokens → Create. Choose a name and an expiry (30, 90, or 365 days). The token value (gdc_pat_…) is shown once — copy it immediately.

Send the token on every request in the Authorization header:

Authorization: Bearer gdc_pat_xxxxxxxxxxxxxxxxxxxxxxxx

Tokens act as you — same permissions, same data access, same tier limits.

Base URL

The API base URL is https://gdca.api.smartdatahub.io/v1.

Core workflow

The API supports the same discover → subscribe → monitor → download flow as the UI:

1. Find the dataset (search or navigate via discover)
2. Fetch dataset details to confirm it is ingestible and get its node_id
3. Create a subscription using the same url and node_id (starts a run immediately)
4. Poll the subscription status until it reaches SUCCESS or FAILED
5. Retrieve the download links

Step 2 is important on the free tier — it ensures the row-count check at subscribe time completes immediately rather than returning a size-verification error.

A concise shell example:

export GDC_PAT=gdc_pat_xxx
BASE=https://gdca.api.smartdatahub.io/v1
auth=(-H "Authorization: Bearer $GDC_PAT" -H "Content-Type: application/json")

# 1. Search for datasets — 'identifier' in results is the same as node_id
curl -s "${auth[@]}" "$BASE/search?q=protected+areas+Finland" | jq '.results[0]'

# 2. Fetch dataset details (confirms ingestibility; use a type-specific url)
DS_URL="https://example.org/wfs?service=WFS&request=GetCapabilities"
DS_NODE_ID="ns:protected_areas"
curl -s "${auth[@]}" -X POST "$BASE/discover/submit" \
  -d "{\"url\":\"$DS_URL\", \"node_id\":\"$DS_NODE_ID\"}" | jq '.item | {node_id, is_ingestible, row_count}'

# 3. Subscribe using the same url and node_id (starts a run immediately — do not call /execute after create)
TASK=$(curl -s "${auth[@]}" -X POST "$BASE/tasks" -d "{
  \"source_uri\": \"$DS_URL\",
  \"source_type\": \"WFS\",
  \"source_dataset_name\": \"protected_areas\",
  \"node_id\": \"$DS_NODE_ID\",
  \"schedule\": \"on-demand\"
}" | jq -r .subscription_id)

# 4. Poll until terminal
curl -s "${auth[@]}" "$BASE/tasks/$TASK" | jq '{ingestion_status, current_phase}'

# 5. Get download links (available after SUCCESS)
curl -s "${auth[@]}" "$BASE/data/$TASK/files" | jq

For the full annotated example and all endpoint shapes, see the API Reference.

What the API provides

Area	What you can do
Search	Full-text search across the dataset catalogue
Discovery	Explore a data service URL (async submit → poll)
Subscriptions	Create, list, get, enable/suspend, change schedule, run now, delete
Runs	List run history for a subscription
Downloads	Get pre-signed download links for completed runs
Connections	Create, list, update, delete saved authenticated connections (paid)
Settings	Read and update notification settings; check your tier and usage
Health	Check the health of one or more data service URLs

Tier limits apply to the API

The same free tier limits apply to API usage:

• Maximum 10 active subscriptions
• Maximum 10 retrieval runs per day
• Maximum 10,000 rows per dataset
• Only on-demand schedule (no recurring)
• Rate limit: 60 requests/minute (Free) / 300 requests/minute (Paid)

Check your tier and current usage before building flows around limits:

curl -s "${auth[@]}" "$BASE/settings/free-tier-status" | jq

Exceptions

A small number of capabilities are intentionally not available via the API:

• PAT management — a PAT cannot create or revoke other PATs. Use the Settings screen.
• Billing checkout / portal — upgrade and billing management are UI-only (human actions).
• Session management — the API uses PAT authentication; whoami confirms token identity.

AI coding assistant integration

The API is designed for use with AI coding assistants. See AI Assistant Integration for guidance on giving an assistant your PAT and prompting it to run the full workflow.