Spaces:

CommunityOne
/

open-navigator

Running on CPU Upgrade

App Files Files Community

open-navigator / web_docs /docs /data-sources /charity-navigator.md

jcbowyer

Clean HuggingFace deployment without binary files

e59d91d 21 days ago

preview code

Raw

History Blame Contribute Delete

12.7 kB

metadata

sidebar_position: 6
title: Charity Navigator API
description: >-
  Enrich nonprofit profiles with independent Charity Navigator star ratings,
  mission statements, websites, and active advisories.
tags:
  - data-source
  - nonprofits
  - commercial
  - api

Charity Navigator API

Powered by Charity Navigator

Enrich nonprofit profiles with independent ratings, mission statements, and organizational metrics from Charity Navigator's comprehensive database.

:::info At a glance


Provider	Charity Navigator, Inc.
Coverage	U.S. registered nonprofits — all 1.9M with basics; ~200K rated
Update cadence	Annual rating refresh
License	Charity Navigator API Terms — attribution & link-back required (see "Legal & Compliance" below and the Legal index)
Cost	Free, capped at 1,000 API calls/day
Access method	GraphQL — `https://api.charitynavigator.org/graphql` (Bearer token)
Our pipeline	On-demand enrichment keyed by EIN; cached locally before merge into gold nonprofit tables
:::

Overview

Charity Navigator is America's largest and most-utilized independent nonprofit evaluator. Their API provides access to:

Star Ratings: Independent 0-4 star ratings (Encompass Rating System)
Mission Statements: Organization purpose and activities
Website URLs: Official organization websites
Organizational Metrics: Financial health, accountability, transparency
Active Advisories: Important alerts about organization status

Data Available

Data Fields

The Charity Navigator GraphQL API provides the following fields for all registered nonprofits:

Field	Description	Coverage
EIN	Employer Identification Number	100%
Charity Name	Official organization name	100%
Mission	Organization mission statement	Rated orgs only*
Website URL	Official website address	~80%
Charity Navigator URL	Link to CN profile page	Rated orgs only*
Category	Nonprofit category	Rated orgs only*
Cause	Primary cause area	Rated orgs only*
Address	Street, City, State, Zip, Country	100%
Active Advisories	Status alerts	All orgs
Encompass Star Rating	0-4 star rating	Rated orgs only*
Encompass Score	Numerical rating score	Rated orgs only*
Rating Publication Date	When rating was published	Rated orgs only*

*Fields marked with asterisk are only available for organizations that have been rated by Charity Navigator.

Usage Limits & Compliance

Rate Limits

Maximum: 1,000 API calls per day
No bulk downloads: Use incremental enrichment
Caching allowed: For performance only (not redistribution)

Attribution Requirements

MANDATORY on all pages displaying Charity Navigator data:

Text Credit: "Powered by Charity Navigator"
Source Citation: "Data provided by Charity Navigator"

Linkback: All charity names link to their Charity Navigator profile:

<a href="https://www.charitynavigator.org/ein/[EIN]">
  [Organization Name]
</a>

Trademark Notice (once per page or in credits):

CHARITY NAVIGATOR and the CHARITY NAVIGATOR logo are registered trademarks 
of Charity Navigator. All rights reserved. Used with permission.

Link Requirements

Use descriptive anchor text (not "click here")
Do NOT use rel="nofollow" on Charity Navigator links
Allow search engines to crawl all links to charitynavigator.org

✅ Correct:

<a href="https://www.charitynavigator.org/ein/134141945">
  Michael J. Fox Foundation for Parkinson's Research
</a>

❌ Incorrect:

<a href="https://www.CharityNavigator.org/ein/134141945" rel="nofollow">
  Click here
</a>

Star Rating Display

When displaying Charity Navigator star ratings, use official images:

Star Images (PNG format, 239×54px)

Rating	Image URL
4-Star	`https://www.charitynavigator.org/content/dam/cn/cn/icons/four_star.png`
3-Star	`https://www.charitynavigator.org/content/dam/cn/cn/icons/three_star.png`
2-Star	`https://www.charitynavigator.org/content/dam/cn/cn/icons/two_star.png`
1-Star	`https://www.charitynavigator.org/content/dam/cn/cn/icons/one_star.png`
0-Star	`https://www.charitynavigator.org/content/dam/cn/cn/icons/zero_star.png`

SVG Format (Vectors)

Replace .png with .svg in the URLs above for scalable vector graphics.

Display Guidelines

Star images MUST link to the charity's Charity Navigator profile page
Do NOT stretch or skew images (maintain aspect ratio)
Prefer full-color versions; ensure knockout (white) versions pass accessibility tests

Example HTML:

<a href="https://www.charitynavigator.org/ein/134141945">
  <img src="https://www.charitynavigator.org/content/dam/cn/cn/icons/four_star.png" 
       alt="Four-star rating by Charity Navigator" />
</a>

Integration Example

Python with Requests

import requests

# GraphQL API endpoint
url = "https://api.charitynavigator.org/graphql"

# Example query
query = """
query {
  charity(ein: "134141945") {
    ein
    charityName
    mission
    websiteUrl
    charityNavigatorUrl
    category
    cause
    mailingAddress {
      streetAddress1
      city
      state
      postalCode
    }
    currentRating {
      rating
      ratingDate
    }
  }
}
"""

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json={"query": query}, headers=headers)
data = response.json()

print(f"Charity: {data['data']['charity']['charityName']}")
print(f"Rating: {data['data']['charity']['currentRating']['rating']} stars")
print(f"Mission: {data['data']['charity']['mission']}")

Enrichment Workflow

Extract EINs from your nonprofit dataset
Batch requests (max 1,000/day)
Cache responses locally to avoid re-fetching
Merge data into your gold tables
Track update date to know when to refresh

Data Comparison

Charity Navigator vs Other Sources

Data Field	Charity Navigator	IRS EO-BMF	Form 990 XML	BigQuery
Star Rating	✅ (0-4 stars)	❌	❌	❌
Mission	✅ (Rated orgs)	❌	✅ (30-40%)	✅ (30-40%)
Website	✅ (~80%)	❌	❌	✅ (30-40%)
Financials	✅ (Summary)	❌	✅ (Detailed)	✅ (Detailed)
Coverage	~200K rated	1.9M orgs	~300K/year	5M+ records
Update Freq	Annual	Monthly	Annual	Annual
Independent Rating	✅ UNIQUE	❌	❌	❌

Key Advantages:

✅ Only source with independent star ratings
✅ High-quality mission statements (manually reviewed)
✅ Better website URL coverage than Form 990
✅ Active advisories (warnings, alerts)
✅ Nonprofit evaluation methodology is transparent

Limitations:

Only ~200K organizations have ratings (largest orgs prioritized)
Smaller nonprofits may not have Charity Navigator profiles
1,000 API calls/day limit (use caching strategically)

Best Practices

Rate Limit Management

import time
from datetime import datetime, timedelta

class CharityNavigatorClient:
    def __init__(self, api_key, daily_limit=1000):
        self.api_key = api_key
        self.daily_limit = daily_limit
        self.call_count = 0
        self.reset_time = datetime.now() + timedelta(days=1)
    
    def query(self, ein):
        # Check if we've hit the daily limit
        if self.call_count >= self.daily_limit:
            wait_seconds = (self.reset_time - datetime.now()).total_seconds()
            if wait_seconds > 0:
                print(f"Rate limit reached. Waiting {wait_seconds:.0f}s...")
                time.sleep(wait_seconds)
                self.call_count = 0
                self.reset_time = datetime.now() + timedelta(days=1)
        
        # Make API call
        response = self._make_request(ein)
        self.call_count += 1
        
        return response

Caching Strategy

Cache responses to avoid redundant API calls:

import json
from pathlib import Path

cache_dir = Path("data/cache/charity_navigator/")
cache_dir.mkdir(parents=True, exist_ok=True)

def get_charity_data(ein, api_client):
    cache_file = cache_dir / f"{ein}.json"
    
    # Check cache first
    if cache_file.exists():
        with open(cache_file) as f:
            return json.load(f)
    
    # Fetch from API
    data = api_client.query(ein)
    
    # Save to cache
    with open(cache_file, 'w') as f:
        json.dump(data, f, indent=2)
    
    return data

Incremental Updates

Only fetch new/updated ratings:

import pandas as pd
from datetime import datetime, timedelta

def needs_update(last_updated, max_age_days=90):
    """Check if rating needs refresh (default: every 90 days)"""
    if pd.isna(last_updated):
        return True
    
    age = datetime.now() - pd.to_datetime(last_updated)
    return age > timedelta(days=max_age_days)

# Filter nonprofits needing updates
nonprofits = pd.read_parquet("data/gold/nonprofits.parquet")
needs_refresh = nonprofits[
    nonprofits['cn_updated_date'].apply(needs_update)
]

print(f"Need to refresh: {len(needs_refresh):,} organizations")

Schema

Fields to Add to Gold Tables

When enriching your nonprofit dataset, add these fields:

enriched_fields = {
    'cn_star_rating': 'int64',          # 0-4 stars
    'cn_encompass_score': 'float64',    # Numerical score
    'cn_rating_date': 'datetime64',     # When rated
    'cn_mission': 'string',             # Mission statement
    'cn_website': 'string',             # Website URL
    'cn_category': 'string',            # Category
    'cn_cause': 'string',               # Cause area
    'cn_profile_url': 'string',         # Link to CN profile
    'cn_advisory_status': 'string',     # Active advisories
    'cn_updated_date': 'datetime64',    # When we fetched data
}

Cost

FREE with the following limits:

1,000 API calls per day
Beta offering (no fees)
Nonprofit use case

For commercial use or higher volume, contact Charity Navigator: api@charitynavigator.org

Legal & Compliance

API Terms of Use

By using the Charity Navigator API, you agree to:

Rate Limits: Max 1,000 calls/day
Attribution: Display "Powered by Charity Navigator" on all pages
Linkbacks: Link all charity names to their CN profiles
Trademark: Include trademark notice
No Redistribution: Cannot resell or redistribute CN data
No Derivative Ratings: Cannot create competing rating systems
Caching: Only for performance, not redistribution
Termination: CN can terminate access for violations

Intellectual Property

All Charity Navigator data and ratings are proprietary
API and database owned by Charity Navigator, Inc.
Users have no ownership rights to cached data
Feedback/suggestions become CN property

Full Terms

Complete API Terms of Use: https://www.charitynavigator.org/partner/api-terms

Troubleshooting

"No rating available"

Not all nonprofits have Charity Navigator ratings. The service prioritizes:

Larger organizations (>$1M revenue)
National/regional nonprofits
Organizations with public interest

Solution: Check for null ratings and gracefully handle unrated orgs.

"Rate limit exceeded"

Error: Maximum daily API calls (1,000) reached

Solution:

Implement caching (see above)
Process in batches over multiple days
Prioritize most important organizations first

"Invalid EIN"

Error: Organization not found

Possible causes:

EIN typo or formatting error
Organization not in CN database
Inactive/dissolved organization

Solution: Validate EINs before querying, handle 404s gracefully.

Support

API Documentation: https://www.charitynavigator.org/partner/api
Technical Support: api@charitynavigator.org
Website: https://www.charitynavigator.org
Phone: (201) 818-1288