Accessing Scorecard Data¶

Published snapshot downloads¶

Download the 26 June 2026 visualization snapshot, including scores, written assessments and source links. JSON retains nested indicator metadata; CSV puts each indicator's score, assessment and sources into columns. Both retain the generation date and 9 September 2025 source-verification stamp.

Download scorecard JSON Download scorecard CSV

CSV text beginning with spreadsheet formula characters is prefixed with an apostrophe. JSON retains the original text. Identify the snapshot date and assessments used when citing the data; see citation guidance.

Overview¶

The published browser snapshot and local pipeline workbook are distinct research outputs:

Material	Location	Contents
Published visualization snapshot	Downloads above	Three-point scores, written assessments, sources and documentation counts
Canonical pipeline workbook	`data/scorecard/scorecard_main.xlsx`, sheet `UN_194`	Country indicator values and paired source columns
Visualization workbook	`data/scorecard/Global_QueerAI_Child_Scorecard_MASTER.xlsx`, sheet `Scorecard`	Scored visualization input
Convenience exports	Root `scorecard.xlsx`, `.csv`, `.ods`	Copies generated from the canonical workbook

The self-hosted API reads the canonical workbook. It does not return the same schema as the scored browser snapshot.

Option 1: REST API (self-hosted)¶

Quick Start¶

Follow the API Quick Start to install dependencies and start your instance, then query it:

curl http://localhost:5000/api/health
curl 'http://localhost:5000/api/scorecard?region=Africa&per_page=100'
curl http://localhost:5000/api/scorecard/Kenya

Scorecard Endpoints¶

Endpoint	Response under `data`
`/api/scorecard`	`items` containing country, region, region-specific label and indicator count; `pagination` describes the result pages
`/api/scorecard/:country`	Country details and `indicators`; each indicator contains `value` and `source`
`/api/scorecard/indicators/statistics`	Per-field `total_countries` and `value_distribution`

The list endpoint returns summaries. Use country detail for indicator values and sources. The default maximum page size is 100; follow pagination to retrieve the complete collection.

Python Examples¶

Fetch all country summaries, then inspect one country's indicators:

import requests

base = "http://localhost:5000/api"
countries = []
page = 1
while True:
    response = requests.get(
        f"{base}/scorecard", params={"page": page, "per_page": 100}, timeout=30
    )
    response.raise_for_status()
    result = response.json()["data"]
    countries.extend(result["items"])
    if not result["pagination"]["has_next"]:
        break
    page += 1

response = requests.get(f"{base}/scorecard/Kenya", timeout=30)
response.raise_for_status()
kenya = response.json()["data"]
print(kenya["indicators"]["LGBTQ_Legal_Status"])
print(len(countries))

JavaScript Example¶

Query one country's indicator values from your locally running service:

const response = await fetch('http://localhost:5000/api/scorecard/Kenya');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data } = await response.json();
console.log(data.indicators.LGBTQ_Legal_Status);

R Example¶

library(httr)
response <- GET("http://localhost:5000/api/scorecard/Kenya")
stop_for_status(response)
kenya <- content(response, as = "parsed")$data
print(kenya$indicators$LGBTQ_Legal_Status)

Rate Limits¶

Default limits are 100 requests/hour without a key and 1,000 with a key; some routes use different limits. The instance operator configures keys and limits through the deployment guide.

Option 2: CSV Export¶

Generate Exports¶

Run from the repository root:

python pipeline_runner.py --mode scorecard --scorecard-action export

Generated Files¶

The standard export writes:

data/exports/scorecard_summary.csv: country, region and indicator values.
data/exports/scorecard_sources.csv: country, indicator and url for each extracted source URL.
data/exports/scorecard_indicator_counts.csv: indicator, status and count.

Regional and individual-indicator exports are separate operations:

from processors.scorecard_export import ScorecardExporter

exporter = ScorecardExporter()
exporter.export_by_region("Africa")
exporter.export_by_indicator("AI_Policy_Status")

Using CSV Exports¶

import pandas as pd

df = pd.read_csv("data/exports/scorecard_summary.csv")
print(df[["Country", "AI_Policy_Status", "Data_Protection_Law"]].head())

Option 3: Direct File Access¶

Primary File¶

Open data/scorecard/scorecard_main.xlsx, sheet UN_194, for the canonical pipeline inputs.

Using the File¶

import pandas as pd

df = pd.read_excel("data/scorecard/scorecard_main.xlsx", sheet_name="UN_194")
print(df[["Country", "LGBTQ_Legal_Status", "LGBTQ_Legal_Status_Source"]].head())

File Structure¶

Country and region columns sit alongside indicator values and paired _Source columns. The current canonical workbook has one sheet; supporting visualization material is in the separate visualization workbook. For the browser's numerical scores and written justifications, use the published JSON/CSV or the visualization workbook rather than assuming the pipeline workbook has that schema.

Option 4: Pipeline Integration¶

Enrichment Process¶

Document processing adds country indicators where a country match is available. Refresh enrichment in an existing metadata collection with:

python pipeline_runner.py --mode scorecard --scorecard-action enrich

Enriched Metadata¶

A document's scorecard object records the matched country, enrichment timestamp and indicator values/sources. Metadata Schema describes these fields.

Programmatic Access¶

from processors.scorecard import get_all_indicators

print(get_all_indicators("Kenya"))

Comparison Matrix¶

Need	Use
Browser snapshot scores and written assessments	Published JSON/CSV
Local country values and sources through HTTP	Self-hosted API country detail
Workbook research and editing	Canonical `UN_194` sheet
Generated summaries and source lists	Pipeline exports
Add country context to processed documents	Pipeline enrichment

Data Validation¶

Automated Validation¶

python processors/scorecard_validator.py --workers 10

URL checks record reachability, redirects and errors. They do not establish whether a legal interpretation is correct. Outputs are documented in the Scorecard Workflow.

Change Detection¶

python processors/scorecard_diff.py

Content hashes identify changed source pages for review. Years found in assessment text flag possible review candidates; a law's age alone does not make its current status obsolete.

Common Queries¶

Find countries with specific indicators¶

For the browser snapshot, use its scored fields directly:

import requests

response = requests.get("https://grimdata.org/scorecard/data/scorecard.json", timeout=30)
response.raise_for_status()
snapshot = response.json()
countries = [
    c["country"] for c in snapshot["countries"]
    if c["scores"].get("LGBTQ") == 0 and c["scores"].get("SIM") == 0
]
print(countries)

This selects countries assigned zero on both indicators in this snapshot. Open their written assessments to examine the classification.

Regional analysis¶

Filter by region in the country explorer, or pass region=Africa to the API summary endpoint.

Intersectional risk analysis¶

Research Context explains how identification requirements and restrictions on LGBTQ+ expression can interact. The additive score does not calculate those interactions.

Support¶

API reference · Scorecard Workflow · FAQ

Documentation¶

Scorecard overview · Methodology · Visualization · Country explorer