API Documentation

GiveRadar REST API v1

Get API Key Pricing

Contents

Authentication Rate Limits Errors Search Charities Charity Detail Financial Filings News & Sentiment Reviews Platform Stats

Authentication

All API requests require an API key. Get yours free at /api/keys/.

Option 1: Authorization header (recommended)

curl -H "Authorization: Bearer gr_your_key_here" \
  "https://giveradar.com/api/v1/search/?q=oxfam"

Option 2: Query parameter

curl "https://giveradar.com/api/v1/search/?q=oxfam&api_key=gr_your_key_here"

Rate Limits

Tier Daily Limit Price Data Access
Free 100 requests/day $0 Search + basic data
Pro 10,000 requests/day $99/month Full data: financials, officers, contacts
Enterprise Unlimited Custom Bulk export, webhooks, SLA

Limits reset at midnight UTC. Every response includes requests_remaining in the _meta object.

Errors

Code Meaning What to do
401 No API key provided Add your key as a Bearer token
403 Invalid or deactivated key Check your key at /api/keys/
404 Charity not found Check the slug is correct
429 Rate limit exceeded Wait until midnight UTC or upgrade

Charity Detail

GET /api/v1/charity/{slug}/

Get complete charity profile including financials, officers, red flags, and reviews.

Response fields

name — Organization name

trust_score — 0-100 trust score

description — Description

website — Website URL

email — Contact email

phone — Phone number

address — Physical address

city / state_province

annual_revenue — Annual revenue

annual_expenses — Annual expenses

program_expenses — Program spend

overhead_ratio — Overhead %

top_exec_name — CEO/Director

top_exec_compensation — Pay

employee_count — Staff size

founded_year — Year founded

ein — US EIN number

sanctions_status — clear/matched

verified — GiveRadar verified

data_sources — Data provenance

recent_filings — Last 3 filings

officers — Up to 20 officers

red_flags — Active warnings

review_summary — Avg rating + count

Example

curl -H "Authorization: Bearer gr_your_key" \
  "https://giveradar.com/api/v1/charity/american-national-red-cross/"

Financial Filings

GET /api/v1/charity/{slug}/financials/

Get financial filing history (up to 10 years) plus executive compensation and spending breakdown.

Response includes

filings[] — Array of yearly filings: revenue, expenses, program/admin/fundraising spend, assets, liabilities

spending_breakdown — Current program_spend_pct, admin_spend_pct, overhead

executive_compensation — Top exec name, title, compensation

News & Sentiment

GET /api/v1/charity/{slug}/news/

Get recent news articles and average sentiment score for a charity. Powered by GDELT.

Response includes

articles[] — Title, URL, source, language, tone, published date

article_count — Number of articles

average_tone — Sentiment score (negative = bad, positive = good)

Reviews

POST /api/v1/charity/{slug}/reviews/

Submit a review for a charity.

Request body (JSON)

{
  "user_name": "John Doe",
  "user_role": "donor",       // donor, volunteer, beneficiary, employee, other
  "rating": 4,                // 1-5
  "title": "Great organization",
  "comment": "Very transparent..."
}

Platform Stats

GET /api/v1/stats/

Get platform-wide statistics: total charities, countries, red flags, average trust score.

Code Examples

Python

import requests

API_KEY = "gr_your_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Search
resp = requests.get(
    "https://giveradar.com/api/v1/search/",
    params={"q": "unicef", "country": "US"},
    headers=headers,
)
data = resp.json()
for charity in data["results"]:
    print(f"{charity['name']}: {charity['trust_score']}/100")

JavaScript

const API_KEY = 'gr_your_key_here';

const resp = await fetch(
  'https://giveradar.com/api/v1/search/?q=oxfam',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const data = await resp.json();
console.log(data.results);

Our data sources, methodology, and per-country documentation are open source.

matt-timmermans/giveradar-data