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 integrity assessment

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 integrity assessment.

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