AI Assistant Integration

Geo Data Connector's API is designed for use with AI coding assistants such as Claude, ChatGPT, and similar tools. Give the assistant your Personal Access Token and a reference to the API Reference, and it can search for data, create subscriptions, monitor runs, and retrieve download links — all without you touching the UI.

Prerequisites

1. A Geo Data Connector account (Free or Paid).
2. A Personal Access Token — create one at Settings → Personal Access Tokens → Create. Copy the token value (gdc_pat_…) when it is displayed; it is shown only once.
3. An AI coding assistant that can make HTTP requests or generate and run shell scripts.

Giving the assistant context

Paste the following into the assistant's context window (or as a system prompt if your setup supports it):

You have access to the Geo Data Connector API.

Base URL: https://gdca.api.smartdatahub.io/v1
Auth: Authorization: Bearer <your-pat-here>
Content-Type: application/json

The full API reference is at:
https://www.smartdatahub.io/docs/gdc-web-api/

Core workflow:
1. Find the dataset: GET /v1/search?q=<query> (use the result's identifier/node_id)
   OR navigate: POST /v1/discover/submit {url} → poll /v1/discover/status/{ticket_id}
   → drill to a dataset item — its node_id is the same as the search identifier.
2. Use a type-specific URL (e.g. ?service=WFS&request=GetCapabilities).
3. Fetch dataset details: POST /v1/discover/submit {url, node_id}
   → confirms row_count is within your tier's limit before subscribing.
4. Subscribe: POST /v1/tasks {source_uri: <same url>, source_type, source_dataset_name,
   node_id: <same node_id>, schedule}
   - Creating a task starts a run immediately; do NOT call /execute after create.
5. Poll: GET /v1/tasks/{id} until ingestion_status is SUCCESS or FAILED
6. Download: GET /v1/data/{id}/files → pre-signed file URLs (valid ~12 hours)

On the free tier, step 3 is required before step 4 — it ensures the size check
completes immediately. If step 4 returns 422, re-run step 3 and retry.

Files are Parquet with GeoJSON strings in GEOM_WGS84 (not GeoParquet).
Loading into BigQuery: bq load --source_format=PARQUET dataset.table part-*.parquet
Then create a view: ST_GEOGFROMGEOJSON(GEOM_WGS84, make_valid => TRUE) AS geom
Loading into DuckDB: SELECT *, ST_GeomFromGeoJSON(GEOM_WGS84) AS geom FROM read_parquet('*.parquet')

Replace <your-pat-here> with your actual token. For additional detail on request/response shapes, point the assistant to the API Reference.

Example prompts

Once the assistant has context, you can drive the full workflow with natural language:

Finding and subscribing to a dataset:

"Search Geo Data Connector for protected areas in Finland. Show me the top 3 results, then subscribe to the most relevant one with an on-demand schedule."

Checking subscription status:

"List all my Geo Data Connector subscriptions and show me which ones have data available to download."

Triggering a run and downloading:

"Run my 'protected_areas_finland' subscription now and wait for it to complete. Once it's done, give me the download links."

Automating a recurring workflow:

"Create a script that subscribes to the dataset at https://example.org/wfs with dataset name 'monitoring_stations', polls until it completes, and prints the download URLs."

How the API supports assistant use

The Geo Data Connector API is structured to make assistant integration reliable:

• Consistent JSON responses — every endpoint returns JSON; errors always include a human-readable error field.
• No internal identifiers in responses — subscription IDs, run IDs, and other references are opaque strings the assistant can pass back without parsing.
• Async discovery with polling — the assistant submits a discovery request and polls for the result, which avoids timeouts on large services.
• Inline cache — POST /discover/submit may return the result immediately (without a ticket_id) when results are cached. The assistant must handle both paths: check for ticket_id before deciding to poll.
• Clear terminal states — subscription status values (SUCCESS, FAILED, RETRYING, etc.) are unambiguous for the assistant to branch on.

Discovery: handling both async and inline responses

Discovery is asynchronous, but may return an immediate result. Always check the response:

RESP=$(curl -s "${auth[@]}" -X POST "$BASE/discover/submit" \
  -d '{"url":"https://example.org/wfs"}')
TICKET=$(echo "$RESP" | jq -r '.ticket_id // empty')

if [ -n "$TICKET" ]; then
  # Poll for the result
  while true; do
    STATUS=$(curl -s "${auth[@]}" "$BASE/discover/status/$TICKET")
    if echo "$STATUS" | jq -e '.type' > /dev/null 2>&1; then
      echo "$STATUS" | jq  # Done
      break
    fi
    sleep 2
  done
else
  # Inline result — no polling needed
  echo "$RESP" | jq
fi

Rate limits and polling

The assistant should poll discovery status approximately every 2 seconds. Polling too frequently wastes your rate limit allowance (60 req/min on Free, 300 req/min on Paid). If a 429 response is received, the Retry-After header tells the assistant how many seconds to wait before retrying.

free tier constraints

If your account is on the free tier, the assistant must work within these limits:

• Maximum 10 active subscriptions
• Maximum 10 retrieval runs per day
• Datasets with more than 10,000 rows cannot be subscribed
• Only on-demand schedule (daily/weekly/monthly returns 400)

Check your current usage before creating new subscriptions:

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

The assistant can use can_enable_more and can_ingest_now fields from this response to decide whether to proceed.

Security note

Your PAT acts as your identity — treat it like a password. Do not paste it into a prompt that will be shared, logged, or stored in a public location. Revoke and recreate tokens regularly. Manage tokens at Settings → Personal Access Tokens.

Related pages

• API — overview and core workflow
• API Reference — full endpoint reference with request/response shapes
• Tiers and Limits — Free vs Paid constraints
• Settings — how to create and revoke Personal Access Tokens