DataGraph API Documentation

Quick Start

Get started with DataGraph in 3 simple steps:

1. Get your API key

Sign up for a free account and get your API key instantly.

Sign up now →

2. Make your first request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.datagraph.city/api/nyc/query \
  -d '{"query": "Properties under $800K in Brooklyn"}'

3. Parse the response

{
  "results": [...],
  "count": 42,
  "execution_time_ms": 123,
  "query_type": "graph"
}

MCP Setup (Model Context Protocol)

The easiest way to use DataGraph is through any MCP-compatible AI assistant. The datagraph-city-mcp-server (v1.6.0) connects your assistant to 6.9M+ urban data nodes and 15,500+ civic program resources across multiple cities and datasets.

Recommended: Use MCP for the best experience. Your AI assistant can intelligently query city data and provide insights without you writing any code.

1. Get your API key

Sign up at datagraph.city to get a free API key.

2. Configure your MCP client

Add DataGraph to your MCP client configuration. Example for Claude Desktop:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "datagraph": {
      "command": "npx",
      "args": [
        "-y",
        "datagraph-city-mcp-server"
      ],
      "env": {
        "DATAGRAPH_API_KEY": "your_api_key_here"
      }
    }
  }
}

Replace your_api_key_here with your actual API key. Works with any MCP-compatible client.

3. Restart your client and start querying

After saving the configuration, restart your MCP client. Try these example queries:

"Show me subway stations in Brooklyn that are wheelchair accessible"

"What civic programs in Kansas City address violence prevention?"

"Show me GOSR resources in Nova Scotia for mental health"

MCP Server Tools (v1.6.0)

The server exposes these tools to your AI assistant:

Tool Description
list_datasetsList available datasets, optionally filtered by locality
get_locality_schemaGet the graph schema for a locality (node types, relationships)
query_locality_dataQuery data using natural language or Cypher
get_usage_statsCheck your API usage and quota
get_server_infoServer metadata and GOSR framework info

The server also provides prompts (explore_locality_data, analyze_gosr_dataset, cypher_query_builder) that guide multi-step analysis workflows.

Tip: The recommended workflow is list_datasets → get_locality_schema → query_locality_data. Your AI assistant will discover this automatically.

Remote MCP Endpoint (ChatGPT & others)

For AI clients that connect to MCP servers over HTTP (like ChatGPT), DataGraph provides a remote MCP endpoint with the same tools and prompts as the local server.

Endpoint

POST https://api.datagraph.city/mcp

Accepts JSON-RPC 2.0 messages (MCP Streamable HTTP transport). Same 5 tools and 3 prompts as the local npx server.

ChatGPT Setup

  1. Enable Developer Mode: Settings → Apps → Advanced Settings → Developer Mode
  2. Create App: Settings → Apps → Create App
  3. Set the MCP server URL to https://api.datagraph.city/mcp
  4. Configure authentication with your DataGraph API key as a Bearer token
  5. Toggle on the tools you want ChatGPT to use

Authentication

Pass your API key as a Bearer token in the HTTP headers. Tools that need auth (query_locality_data, get_usage_stats) will use it automatically. Read-only tools like list_datasets work without auth. 

Authorization: Bearer dgc_your_api_key_here

Authentication (Direct API Access)

If you're making direct API calls (not using MCP), all requests require authentication using an API key in the Authorization header: 

Authorization: Bearer dgc_your_api_key_here

Security: Never share your API key or commit it to version control. Use environment variables.

API Endpoints

POST /api/{city}/query

Query city data using natural language

{
  "query": "Properties under $800K near transit",
  "city": "nyc",
  "limit": 10
}
GET /me

Get current user information and usage stats

GET /cities

List all supported cities and their available datasets

GET /usage

Get detailed usage statistics and query history

Example Queries

Real Estate

"Show recent property sales in Brooklyn"
"Properties at 552 West 43 Street"
"Find buildings with DOB permits in Manhattan"
"Show property ownership for this address"

DOB Permits & Buildings

"Recent construction permits in Queens"
"Show all permits for a specific building"
"Find buildings with active permits"
"Permits filed by a specific applicant"

Crime & Safety

"Crime statistics in Brooklyn neighborhoods"
"Show complaints by precinct"
"Recent incidents near a location"
"Crime patterns by offense type"

Transit & Location

"Neighborhoods within 0.5 miles of subway"
"Properties with best transit access"
"Commute time to Manhattan from Queens"

Subway Graph Queries

"List all subway stations in Manhattan"
"Show stations on the A train"
"Find connections from Times Square"
"Show transfer stations between L and 1 trains"
"List accessible stations in Brooklyn"

Graph queries leverage station connectivity data to find routes, transfers, and optimal paths through the subway network.

Business Intelligence

"Best neighborhoods for opening a coffee shop"
"Restaurant density by area"
"Retail competition in SoHo"

Supported Cities

City Code Status
New York City (urban data) nyc Active
Un-Lonely NYC (GOSR) unlonely-nyc Active
Kansas City KC360 (GOSR) kc Active
Western PA / Rust Belt (GOSR) rust-belt Active
Nova Scotia (GOSR) nova-scotia Active

Error Handling

401 Unauthorized

Invalid or missing API key

429 Too Many Requests

Rate limit or quota exceeded

404 Not Found

City not available