AI Assistant Integration

Ask a geographic business question and let your assistant do the finding, fetching, and prepping. Geo Data Connector treats AI assistants as first-class users, with two integration paths: the MCP server (recommended for MCP-capable assistants) and the REST API (works with any assistant that can make HTTP requests).

The MCP server (recommended)

If your assistant speaks the Model Context Protocol, connect it to the Geo Data Connector MCP server and the whole workflow — search, discovery, ingestion, downloads — becomes a set of native tools.

• In Databricks: install Geo Data Connector MCP Server from the Databricks Marketplace listing. Open the installed MCP service and click Login to sign in with your email — this creates your account automatically on first sign-in. Enable it for Genie (Agent mode), the AI Playground, or your own agent.

Choosing a model in the AI Playground. Geo Data Connector's tools work with any assistant that can call function tools. If a model returns a tool-call error in the Databricks AI Playground (some reasoning models currently reject function tools there), switch to a model verified for tool use — Claude Sonnet works well, as do Databricks-hosted models we've tested. This is a Playground/model setting, not a Geo Data Connector limitation.

• Any other MCP client (Claude Code, Claude Desktop, Cursor, custom agents): connect to https://mcp.smartdatahub.io/mcp. Clients that support OAuth Dynamic Client Registration can sign in directly; clients that use a Personal Access Token connect the same way with your token as a bearer header. Ready-to-paste client configurations are on the MCP Server page.
• No account yet? Your assistant can call the start_trial tool with no credentials for instant free-tier trial access.

The REST API (any assistant)

Geo Data Connector's API also works with AI coding assistants such as Claude, ChatGPT, and similar tools directly. 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