ODN API

{
  "service_type": "platform",
  "base_url": "https://api.opendatanetwork.com",
  "auth_method": "api_key",
  "auth_config": {
    "header": "X-App-Token",
    "notes": "Socrata-style app token authentication. Anonymous access may work with lower rate limits, but a registered app token is recommended for production use."
  },
  "endpoints": [
    {
      "path": "/metadata/v1",
      "method": "GET",
      "description": "Returns service metadata and available API version information."
    },
    {
      "path": "/data/v1/dataset/{dataset_id}/resources",
      "method": "GET",
      "description": "Lists resources (files/attachments) associated with a given ODN dataset."
    },
    {
      "path": "/data/v1/dataset/{dataset_id}",
      "method": "GET",
      "description": "Retrieves dataset-level metadata and resource listings."
    },
    {
      "path": "/data/v1/dataset",
      "method": "GET",
      "description": "Search/browse available datasets across the Open Data Network."
    },
    {
      "path": "/search/v1/suggest",
      "method": "GET",
      "description": "Autocomplete/suggestion endpoint for dataset and entity names."
    },
    {
      "path": "/search/v1/rank",
      "method": "GET",
      "description": "Ranked search results for datasets, regions, and entities."
    },
    {
      "path": "/search/v1/search",
      "method": "GET",
      "description": "Full search over the Open Data Network index of datasets and entities."
    },
    {
      "path": "/insight/v1/compare",
      "method": "GET",
      "description": "Compare a metric across multiple entities/regions (e.g., crime rates between NYC and Chicago)."
    },
    {
      "path": "/insight/v1/compare/{variable_id}",
      "method": "GET",
      "description": "Compare a specific variable across geographies."
    },
    {
      "path": "/insight/v1/related",
      "method": "GET",
      "description": "Find related datasets/variables for a given entity."
    },
    {
      "path": "/insight/v1/related/{variable_id}",
      "method": "GET",
      "description": "Recommend related variables based on a given variable."
    },
    {
      "path": "/insight/v1/scale",
      "method": "GET",
      "description": "Retrieve scale/ranking information for a variable across entities."
    },
    {
      "path": "/insight/v1/scale/{variable_id}",
      "method": "GET",
      "description": "Rank entities by a specific variable."
    },
    {
      "path": "/insight/v1/values",
      "method": "GET",
      "description": "Get values for a variable, optionally filtered by entity."
    },
    {
      "path": "/insight/v1/values/{variable_id}",
      "method": "GET",
      "description": "Get values for a specific variable."
    },
    {
      "path": "/insight/v1/summary",
      "method": "GET",
      "description": "High-level metric summaries across the network."
    }
  ],
  "pricing_model": {
    "type": "freemium",
    "details": {
      "free_tier": "Public data access is free; anonymous requests allowed with stricter throttling.",
      "app_token": "Free registration at Socrata for a throttling-bypass app token.",
      "notes": "ODN aggregates open government/nonprofit data; underlying Socrata hosting tier determines per-dataset rate limits."
    }
  },
  "rate_limits": {
    "anonymous": "Shared, throttled pool; requests may be rejected under load.",
    "with_app_token": "Higher per-IP quotas; exact numbers not publicly enumerated and vary by Socrata deployment.",
    "notes": "Use of X-App-Token header raises effective limits; avoid parallel bursts."
  },
  "capabilities": [
    "Dataset discovery and metadata search across thousands of government/nonprofit portals",
    "Entity and region resolution (cities, counties, states, etc.)",
    "Cross-geography insight comparison for shared variables (e.g., crime, health, transit)",
    "Ranking and scaling of entities by metric",
    "Related-variable and related-dataset recommendations",
    "Resource and attachment retrieval for datasets",
    "Search suggestions and ranked search results",
    "Federated access to Socrata-hosted open data without per-portal integration",
    "JSON responses suitable for dashboards, journalism, and civic tech apps"
  ],
  "raw_analysis": "The Socrata OpenDataNetwork (ODN) API is a federated discovery and insight layer over the Socrata open data ecosystem. Rather than hosting data itself, it indexes and normalizes metadata and entity relationships across thousands of public-sector portals (cities, states, federal agencies, nonprofits), so developers can search, compare, and rank cross-jurisdictional metrics without integrating each portal individually.\n\nWhat it does: provides search (suggest/rank/search), dataset metadata and resource listing, and an 'insight' family of endpoints for comparing and ranking variables across geographies (e.g., compare a metric between NYC and Chicago, rank all entities by a variable, fetch values for a variable, or s

1/3 tests passed

```json
{
  "overall": 68,
  "dimensions": {
    "token_efficiency": 7.5,
    "first_try_success": 6.5,
    "response_parseability": 8.5,
    "error_clarity": 7.0,
    "doc_quality": 6.5,
    "auth_simplicity": 7.5,
    "latency": 9.0,
    "consistency": 7.0
  },
  "pricing_normalized": {
    "model": "freemium",
    "free_tier": true,
    "anonymous_access": true,
    "app_token_required": false,
    "app_token_required_for_robots_and_llms": true,
    "paid_tiers": "determined by Socrata hosting tier"
  },
  "issues": [
    "robots.txt and llms.txt return 403 requiring an app_token, blocking crawler/agent discovery of site policy and AI-facing docs",
    "No security headers on responses (may affect trust/compliance posture)",
    "App token registration still requires Socrata signup — mild friction for first-time API users",
    "Documentation lives at an apiary.io subdomain, which is a third-party docs host (potential lifecycle/stability concern)",
    "Per-dataset rate limits are inherited from Socrata hosting tiers, making throttling behavior inconsistent across the federated catalog"
  ],
  "recommendations": [
    "Serve a public llms.txt and robots.txt without requiring an app_token so agents can programmatically understand the platform",
    "Return structured error bodies with a stable schema and include a machine-readable list of available endpoints in error responses",
    "Publish a compact OpenAPI/JSON schema for the search, resolve, compare, rank, and related endpoints so agents can generate calls on the first try",
    "Document throttling tiers explicitly per endpoint and per dataset host, and expose rate-limit headers (X-RateLimit-Remaining, etc.)",
    "Add standard security headers (HSTS, CSP, X-Content-Type-Options) to improve trust signals",
    "Consider supporting OAuth device flow or simple API key issuance without requiring the full Socrata account dance",
    "Provide a 'quickstart in one curl' example on the landing page so first-try success improves",
    "Mirror docs to a first-party domain (e.g., docs.odn.socrata.com) instead of apiary.io to reduce third-party dependency risk"
  ]
}
```