API Quick Reference

Fast access to GRIMdata via REST API

Start the API

# Install dependencies
pip install -r api_requirements.txt

# Run development server
python run_api.py

# Or with Docker
docker-compose up -d

Server runs at: http://localhost:5000

---

14 Production-Ready Endpoints

Health & Info

Endpoint	Description
GET /api/health	Health check
GET /api/info	System statistics

Documents

Endpoint	Description	Rate Limit
GET /api/documents	List documents (with filters)	200/2000 per hour*
GET /api/documents/:id	Get document details	100/1000 per hour*

Filters: country, region, tags, year, year_min, year_max, source, doc_type, page, per_page, sort_by, sort_order

Scorecard

Endpoint	Description
GET /api/scorecard	All countries summary
GET /api/scorecard/:country	Country details
GET /api/scorecard/indicators/statistics	Indicator statistics

Filters: region, page, per_page

Tags

Endpoint	Description	Rate Limit
GET /api/tags	Tag frequency analysis	100/1000 per hour*
GET /api/tags/versions	Available tag versions	100/1000 per hour*

Filters: version, country, region, year, year_min, year_max

Timeline

Endpoint	Description
GET /api/timeline/tags	Tags over time (year × tag matrix)

Filters: version, country, region, year_min, year_max

Export

Endpoint	Description	Rate Limit
GET /api/export	List available export formats	100/1000 per hour*
GET /api/export/:format	Download CSV datasets	20/200 per hour*

Formats: scorecard_summary, tags_summary, documents_list

*Rate limits: public / authenticated (with API key)

---

Authentication (Optional)

Use API key for higher rate limits:

# Add X-API-Key header
curl -H "X-API-Key: your-api-key" http://localhost:5000/api/documents

Rate Limits: - Public (no key): 100 requests/hour (20/hr for exports) - Authenticated: 1000 requests/hour (200/hr for exports)

---

Quick Examples

DocumentsScorecardTags & TimelineExportPython

# List all documents
curl http://localhost:5000/api/documents

# Filter by country
curl "http://localhost:5000/api/documents?country=Kenya"

# Filter by tags and region
curl "http://localhost:5000/api/documents?tags=AI&region=Africa"

# Pagination with sorting
curl "http://localhost:5000/api/documents?page=1&per_page=20&sort_by=year&sort_order=desc"

# All countries
curl http://localhost:5000/api/scorecard

# Specific country
curl http://localhost:5000/api/scorecard/Kenya

# Filter by region
curl "http://localhost:5000/api/scorecard?region=Africa"

# Indicator statistics
curl http://localhost:5000/api/scorecard/indicators/statistics

# Get tag frequency for Africa
curl "http://localhost:5000/api/tags?region=Africa&version=tags_v3"

# Get available tag versions
curl http://localhost:5000/api/tags/versions

# Get tags over time (2020-2024)
curl "http://localhost:5000/api/timeline/tags?year_min=2020&year_max=2024"

# List export formats
curl http://localhost:5000/api/export

# Download scorecard CSV
curl "http://localhost:5000/api/export/scorecard_summary" -o scorecard.csv

# Download tags summary
curl "http://localhost:5000/api/export/tags_summary?version=tags_v3" -o tags.csv

import requests

# Optional: Use API key for higher limits
headers = {"X-API-Key": "your-api-key"}

# Get documents filtered by country
response = requests.get(
    "http://localhost:5000/api/documents?country=Kenya",
    headers=headers
)
documents = response.json()["data"]["items"]

# Get scorecard for Kenya
response = requests.get(
    "http://localhost:5000/api/scorecard/Kenya",
    headers=headers
)
scorecard = response.json()["data"]
print(scorecard["indicators"])

# Get tag frequency for Africa
response = requests.get(
    "http://localhost:5000/api/tags?region=Africa",
    headers=headers
)
tags = response.json()["data"]["tags"]

# Download CSV export
response = requests.get(
    "http://localhost:5000/api/export/scorecard_summary",
    headers=headers
)
with open("scorecard.csv", "wb") as f:
    f.write(response.content)

---

Response Format

Success:

{
  "status": "success",
  "data": { ... },
  "timestamp": "2026-01-25T10:30:00Z"
}

Paginated:

{
  "status": "success",
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 78,
      "total_pages": 4,
      "has_next": true,
      "has_prev": false
    }
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

Error:

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Document not found",
    "details": {}
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

Rate Limit Error (429):

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later or use an API key for higher limits."
  },
  "timestamp": "2026-01-25T10:30:00Z"
}

---

Features

Feature	Description
Advanced Filtering	Filter by country, region, tags, year, source, document type
Pagination	Configurable page size (max 100 items per page)
Sorting	Sort by any field, ascending or descending
Caching	15-minute cache for documents, 1-hour for scorecard
Validation	All query parameters validated with clear error messages
Standard Responses	Consistent JSON structure across all endpoints
Authentication	Optional API keys for higher rate limits
Rate Limiting	100-2000 requests/hour based on authentication
Docker Ready	Complete Docker + docker-compose setup

---

Common Queries

Get documents about AI policy in Africa:

curl "http://localhost:5000/api/documents?region=Africa&tags=AI"

Get tag frequency for child rights in 2024:

curl "http://localhost:5000/api/tags?tags=ChildRights&year=2024"

Get LGBTQ+ legal status for all countries:

curl http://localhost:5000/api/scorecard | jq '.data.items[] | {country, lgbtq_status: .LGBTQ_Legal_Status}'

Download all scorecard data:

curl "http://localhost:5000/api/export/scorecard_summary" -o scorecard.csv

Get timeline of AI tags (2018-2024):

curl "http://localhost:5000/api/timeline/tags?year_min=2018&year_max=2024" | jq '.data.timeline'

Get countries with comprehensive data protection:

import requests
response = requests.get("http://localhost:5000/api/scorecard?per_page=200")
countries = response.json()["data"]["items"]
comprehensive = [c for c in countries if c.get("Data_Protection_Law") == "Comprehensive Law"]
print(f"Found {len(comprehensive)} countries with comprehensive data protection")

---

Production Deployment

Deploy with Docker:

# Clone repository
git clone https://github.com/MissCrispenCakes/DigitalChild.git
cd DigitalChild

# Configure environment
cp .env.example .env
# Edit .env with your API keys and settings

# Start services (API + Redis + Nginx)
docker-compose up -d

# Check status
docker-compose ps
curl http://localhost:5000/api/health

Complete deployment guide: Production Deployment

---

Full Documentation

For complete API documentation including:

• All endpoint parameters and schemas
• Response codes and error handling
• Authentication setup
• Rate limiting details
• Docker deployment guide
• Performance optimization
• Security best practices

See: Full API Documentation | API Quick Start Guide

---

Test the API

Quick health check:

# Check all endpoints
curl http://localhost:5000/api/health
curl http://localhost:5000/api/info
curl http://localhost:5000/api/documents
curl http://localhost:5000/api/scorecard
curl http://localhost:5000/api/tags
curl http://localhost:5000/api/export

All 104 integration tests passing (100% success rate)

# Run test suite
pytest tests/api/ -v

---

Last updated: January 2026 (Phase 4 Complete - 14 endpoints operational)