Public API v1

Integrate BigDataSEO.com crawl architecture intelligence into your workflows. Bearer token auth, 100 req/day free tier.

Authentication

All public API endpoints require an API key passed via the Authorization header. Generate keys at /account/api-keys.

curl -H "Authorization: Bearer bds_YOUR_KEY_HERE" \
  "https://bigdataseo.com/api/v1/riba-calculate?n=500000"

Rate limits: 100 requests/day (free tier). Resets at midnight UTC. Rate limit headers are returned on 429 responses.

Base URL

https://bigdataseo.com/api/v1

Public Endpoints

GET /api/v1/riba-calculate

Calculate RIBA tier, bucket size, and tree structure for a dataset of N pages.

Parameters

Param	Type	Required	Description
`n`	integer	Yes	Total number of pages/records
`minBucket`	integer	No	Minimum bucket size (default: 100)
`maxBucket`	integer	No	Maximum bucket size (default: 1000)

Response

{
  "n": 500000,
  "tier": "Large",
  "sqrtN": 708,
  "bucketSize": 708,
  "rootPages": 707,
  "depth": 2,
  "browsePages": 708,
  "leafPages": 500000,
  "browseOverheadPercent": 0.1416,
  "formula": "bucket_size = clamp(√500000, 100, 1000) = 708"
}

POST /api/v1/score

Run the 7-dimension RIBA scoring engine. Accepts a single URL or a dataset of pages (max 10,000).

Request Body (URL mode)

{ "url": "/products/shoes", "title": "Shoes", "category": "Footwear" }

Request Body (Dataset mode)

{
  "pages": [
    { "url": "/products/shoes", "title": "Shoes", "category": "Footwear" },
    { "url": "/products/boots", "title": "Boots", "category": "Footwear" }
  ]
}

Response

{
  "score": {
    "overallScore": 78.3,
    "overallGrade": "B",
    "dimensions": { ... },
    "recommendations": [ ... ]
  }
}

POST /api/v1/generate-brief

Generate a Vibe Coding Brief for building RIBA-compliant browse architecture.

Request Body

{
  "name": "US Product Catalog",
  "recordCount": 50000,
  "vertical": "ecommerce",
  "fields": ["title", "url", "category", "price"],
  "siteUrl": "https://example.com"
}

Response

{
  "brief": {
    "projectName": "US Product Catalog",
    "ribaTier": "Medium",
    "architecture": { "bucketSize": 224, "rootBrowsePages": 224 },
    "promptSuggestion": "Build a medium-scale browse architecture...",
    "urlPatterns": { ... },
    "checklistItems": [ ... ]
  }
}

GET /api/v1/location-architect

Generate a RIBA-compliant location page architecture spec.

Parameters

Param	Type	Required	Description
`country`	string	No	Country code: us, uk, ca, au (default: us)
`domain`	string	No	Your domain (default: example.com)
`services`	string	No	Comma-separated services list
`urlStyle`	string	No	location-first or service-first (default: location-first)

Response

{
  "country": "United States",
  "totalUrls": 45,
  "cityCount": 20,
  "maxDepth": 3,
  "ribaCompliant": true,
  "locations": [ { "path": "/california/", "type": "region", "depth": 1 }, ... ]
}

GET /api/v1/standards/:slug

Retrieve a specific RIBA SEO standard as JSON. See also GET /api/v1/standards for all standards.

Response

{
  "standard": {
    "slug": "riba-001-root-browse-page",
    "name": "Root Browse Page",
    "category": "Architecture",
    "status": "Active",
    "spec": "...",
    "rule": "...",
    "rationale": "...",
    "implementation": "...",
    "violations": "...",
    "fix": "..."
  }
}

GET /api/v1/standards

List all RIBA SEO standards with slug, name, category, and status.

GET /api/v1/registry

List all verified and self-reported RIBA Registry entries with scores.

Response

{
  "entries": [
    {
      "domain": "example.com",
      "vertical": "ecommerce",
      "score": 88.5,
      "grade": "A",
      "status": "verified",
      "pageCount": 250000
    }
  ],
  "count": 1
}

Account API (Session Auth)

These endpoints use session-based authentication (cookie). Log in at /login first.

curl -c cookies.txt -X POST https://bigdataseo.com/login \
  -d "email=you@example.com&password=yourpassword"
curl -b cookies.txt https://bigdataseo.com/api/v1/me

Method	Endpoint	Description
`GET`	`/api/v1/me`	Current user profile
`GET`	`/api/v1/sites`	List registered sites
`GET`	`/api/v1/sites/:id`	Site detail with datasets/scores
`GET`	`/api/v1/datasets`	List datasets
`GET`	`/api/v1/datasets/:id`	Dataset with RIBA scores
`GET`	`/api/v1/scores`	All RIBA scores
`GET`	`/api/v1/deliverables`	List deliverables
`POST`	`/api/deliverables`	Save a new deliverable

Error Responses

All errors return JSON with an error field:

{ "error": "Missing API key. Include 'Authorization: Bearer bds_...' header." }  // 401
{ "error": "Daily limit of 100 requests exceeded." }                              // 429
{ "error": "Standard 'invalid' not found." }                                      // 404
{ "error": "Internal server error" }                                              // 500

Getting Started

Create an account
Go to API Keys and generate a key
Copy the key (shown only once) and store it securely
Include it in the Authorization: Bearer bds_... header