SDKs overview

Charity Search offers Software Development Kits (SDKs) and primary language examples to facilitate integration with its Charity Search API. These tools are designed to simplify the process of accessing and utilizing charity data, such as organizational details, financial information, and impact metrics. The API itself is documented to provide clear guidance for direct HTTP requests, with authentication primarily handled via API keys for secure access. The documentation also includes interactive examples to assist developers in understanding various endpoints and common use cases.

For developers preferring to work with pre-built client libraries, Charity Search provides official SDKs in popular programming languages. These SDKs abstract away the complexities of HTTP requests, JSON parsing, and error handling, allowing developers to focus on application logic. Beyond the official offerings, the developer community may contribute additional libraries, though these are typically not maintained by Charity Search directly. The primary goal of both official SDKs and direct API access is to enable efficient discovery, due diligence, and integration of charity data into various applications and research tools.

Official SDKs by language

Charity Search provides official SDKs for Python and Node.js, which are designed to offer a consistent and idiomatic interface for interacting with the Charity Search API. These SDKs encapsulate the API's endpoints and data structures into language-specific objects and methods, reducing the need for manual HTTP request construction and response parsing. The official documentation for the Charity Search API serves as the authoritative source for details on each endpoint and its parameters, which the SDKs then implement.

The following table outlines the currently available official SDKs:

Language Package Name Install Command Maturity
Python charitysearch-python pip install charitysearch-python Stable
Node.js @charitysearch/node npm install @charitysearch/node Stable

Each SDK is maintained by Charity Search to ensure compatibility with the latest API versions and to provide reliable functionality. Developers are encouraged to refer to the specific SDK documentation pages for detailed usage instructions and examples, accessible via the main Charity Search API documentation.

Installation

Installing the Charity Search SDKs is performed using standard package managers for Python and Node.js. Prior to installation, ensure that you have the appropriate runtime environment set up on your system.

Python SDK Installation

The Python SDK can be installed using pip, the Python package installer. It is recommended to use a virtual environment to manage dependencies for your project. For more information on Python package management, consult the Google Cloud Python setup guide.

pip install charitysearch-python

After installation, you can import the library into your Python scripts:

import charitysearch

client = charitysearch.Client(api_key="YOUR_API_KEY")

Node.js SDK Installation

The Node.js SDK is available via npm (Node Package Manager). Ensure you have Node.js and npm installed. For details on installing Node.js, refer to the Mozilla Developer Network Node.js documentation.

npm install @charitysearch/node

Once installed, you can require or import the module into your JavaScript or TypeScript files:

const CharitySearch = require('@charitysearch/node');
// Or using ES modules:
// import CharitySearch from '@charitysearch/node';

const client = new CharitySearch.Client('YOUR_API_KEY');

cURL Examples

While not an SDK, cURL examples are provided within the Charity Search API documentation to demonstrate direct HTTP requests. This method requires manual construction of request headers and bodies, but offers maximum flexibility and is useful for testing without a language-specific client library. A typical cURL command for authentication might look like this:

curl -X GET "https://api.charitysearch.org/v1/charities?q=red%20cross" \n     -H "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual API key, which can be obtained after signing up for a Charity Search plan, including the free Developer Plan. The use of Bearer token authentication is a common practice for securing web APIs, as detailed in the IETF RFC 6750 for Bearer Token Usage.

Quickstart example

This section provides a quickstart example for both the Python and Node.js SDKs, demonstrating how to retrieve a list of charities. Before running these examples, ensure you have installed the respective SDK and replaced YOUR_API_KEY with your actual Charity Search API key.

Python Quickstart

This Python example initializes the client and searches for charities matching 'environment'.

import charitysearch
import os

# It's recommended to load your API key from environment variables
# For demonstration, you can replace os.environ.get('CHARITYSEARCH_API_KEY')
# with your actual key string 'sk-xxxxxxxxxxxxxxxxxxxx'
api_key = os.environ.get('CHARITYSEARCH_API_KEY', 'YOUR_API_KEY')

if not api_key or api_key == 'YOUR_API_KEY':
    print("Error: Please set your CHARITYSEARCH_API_KEY environment variable or replace 'YOUR_API_KEY'.")
    exit(1)

try:
    client = charitysearch.Client(api_key=api_key)

    print("Searching for charities related to 'environment'...")
    search_results = client.charities.search(query="environment", limit=5)

    if search_results and search_results.data:
        print(f"Found {len(search_results.data)} charities:")
        for charity in search_results.data:
            print(f"- {charity.name} (EIN: {charity.ein})")
            if charity.mission:
                print(f"  Mission: {charity.mission[:100]}...")
    else:
        print("No charities found for 'environment'.")

except charitysearch.exceptions.CharitySearchAPIError as e:
    print(f"API Error: {e.status_code} - {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Node.js Quickstart

This Node.js example performs a similar search for 'environment' related charities.

const CharitySearch = require('@charitysearch/node');

// It's recommended to load your API key from environment variables
// For demonstration, you can replace process.env.CHARITYSEARCH_API_KEY
// with your actual key string 'sk-xxxxxxxxxxxxxxxxxxxx'
const apiKey = process.env.CHARITYSEARCH_API_KEY || 'YOUR_API_KEY';

if (!apiKey || apiKey === 'YOUR_API_KEY') {
  console.error(
    "Error: Please set your CHARITYSEARCH_API_KEY environment variable or replace 'YOUR_API_KEY'."
  );
  process.exit(1);
}

async function searchCharities() {
  try {
    const client = new CharitySearch.Client(apiKey);

    console.log("Searching for charities related to 'environment'...");
    const searchResults = await client.charities.search({ query: 'environment', limit: 5 });

    if (searchResults && searchResults.data && searchResults.data.length > 0) {
      console.log(`Found ${searchResults.data.length} charities:`);
      searchResults.data.forEach((charity) => {
        console.log(`- ${charity.name} (EIN: ${charity.ein})`);
        if (charity.mission) {
          console.log(`  Mission: ${charity.mission.substring(0, 100)}...`);
        }
      });
    } else {
      console.log("No charities found for 'environment'.");
    }
  } catch (error) {
    if (error.response) {
      console.error(
        `API Error: ${error.response.status} - ${error.response.data.message}`
      );
    } else {
      console.error(`An unexpected error occurred: ${error.message}`);
    }
    process.exit(1);
  }
}

searchCharities();

These examples demonstrate basic initialization, a search query, and iteration through results. For more advanced features and endpoint usage, refer to the detailed Charity Search API documentation.

Community libraries

While Charity Search provides official SDKs for Python and Node.js, the broader developer community may also contribute open-source libraries or wrappers. These community-driven projects can offer alternative language bindings, specialized functionality, or integrations with other platforms. However, it is important to note that community libraries are not officially supported or maintained by Charity Search. Their stability, security, and compatibility with future API updates may vary.

Developers considering community libraries should review their source code, check for active maintenance, and understand the licensing terms before integrating them into production environments. The Google Open Source community guidelines provide a framework for evaluating such projects. As of the current date, specific widely adopted community libraries for Charity Search have not been formally identified or endorsed by Charity Search. Developers seeking additional tools are encouraged to explore public code repositories like GitHub for community contributions related to charitysearch or charity search api.

If you develop a community library or discover one that is useful, consider contributing to its documentation or sharing it within relevant developer forums to enhance the ecosystem for other Charity Search users. Always prioritize security and data integrity when using third-party code, especially when handling API keys or sensitive information. Charity Search recommends using their official documentation and SDKs for the most reliable and secure integration.