The GuideStar APIs deliver comprehensive current data from GuideStar's database of Nonprofit and Charitable Organizations and Foundations. Return data is available in either JSON or XML
The GuideStar API site provides 3 ways to get started:
1. GuideStar Production APIs
GuideStar Production APIs are subscription-based, and include:
- CharityCheck PDF,
- Exchange (Profile Update Program data)
- and Search.
2. The GuideStar QuickStart API
GuideStar QuickStart APIs are free APIs intended to provide developers with an easy way to experiment with the integration of GuideStar data into existing applications. The Quickstart APIs provide two interfaces:
- QuickstartSearch API allows keyword and wildcard searches.
- QuickstartDetail API provides a fixed-format data set in either XML or JSON format.
Software that integrates these APIs can be quickly modified to use any of GuideStar's production APIs. Learn more…
3. The GuideStar API Sandbox
The API Sandbox provides complete API functionality with a limited data set. API users can use this site to prototype software for demonstrations or in anticipation of becoming a paid subscriber to the full-data version of Guidestar's APIs. Developers should note that this data is not guaranteed to be current and is refreshed only on occasion. The interfaces and functionality are identical to the production versions. Learn more…
GuideStar Production APIs
- GuideStar Charity Check API
- GuideStar Charity Check PDF API
- GuideStar Exchange API
- GuideStar Detail API
- GuideStar Search API Version 1_1.
- Return Codes
Use these code examples as suggestions for coding API access using cURL, C# .NET, Java, Ruby, or PHP. These examples use the search API. Use these examples as a template and substitute the URL from the tables below for the API you need.
Use these classes to hold deserialized API data
What is an API Key? Why and how should I use one?
This is considered to be unsafe because it removes access control for the APIs.
GuideStar Charity Check API
GuideStar CharityCheck is the only pre-grant due-diligence tool that is 100% compliant with IRS requirements.
The GuideStar CharityCheck API provides this essential data via our REST API in XML or JSON formats.
GuideStar Charity Check PDF API
The GuideStar CharityCheck PDF API allows user applications to retrieve a binary data stream that can be saved and rendered as an Adobe PDF document. The calling program must invoke a PDF-enabled browser or the Adobe Acrobat application to display the PDF.
An example of how to invoke the CharityCheck PDF in C# is here. The first part explains the deprecated SOAP web service. The second part describes the REST API for the CharityCheck PDF:
GuideStar Exchange API
The GuideStar Exchange API combines nonprofit-supplied information with data from other sources to provide comprehensive information about millions of organizations. Organizations that choose to participate in the GuideStar Profile Update Program (formerly "GuideStar Exchange") provide additional data that is more comprehensive than the data GuideStar collects from the IRS Returns for an organization. This data is made available through the Exchange API.
Use the GuideStar Search API with an organization's EIN to find the Organization ID.
GuideStar Detail API
The GuideStar Detail API combines nonprofit-supplied information with data from other sources to provide comprehensive information about millions of organizations.
GuideStar Search API Version 1_1.
Search GuideStar's data about nonprofits and quickly find organizations most relevant to your needs. You can use those results to get more data from our other APIs.
GuideStar’s Search APIs use the Lucene Search Engine and there is a good deal of technical information about using the Lucene API query syntax available on the internet. For example see: lucene.apache.org queryparsersyntax.html
Some technical details of the Search API can be found here.
Here are some examples of how to make basic calls using the GuideStar Search API:
|q||The 'q' parameter is the main query for the request.|
|p||The 'p' parameter is used to paginate results from a query where each page has "r" NPOs (see 'r' parameter). The 'p' parameter specifies which "page" of "r" NPOs should be returned. The default value is 1 and returns NPOs 1..r. A query with p=2&r=5 returns NPOs 6-10 from the overall return set for the query. This allows users to obtain as many return results for a particular query as desired.|
The 'r' parameter specifies the number of NPOs returned on each page for values of 1 through 25. The default is 10 NPOs per page.
An implementation of the Search API that displays 50 or 100 results would need to make 2 calls with an "r" parameter of 25 (e.g., "&r=25") to get 50 results or 4 calls to get 100 results. The results can be stored in a list in the calling program and then displayed once the results are compiled.
|https://data.guidestar.org/v1_1/search?q=ein:54-1774039||Search for an organization with an EIN = 54-1774039|
Search for all organizations with an IRS Foundation Code = 15
|https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2||Search for IRS Foundation Code = 15 and return "page" 2 of the result|
|https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&r=5||Search for IRS Foundation Code = 15 and return 5 results|
|https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2&r=5||Search for IRS Foundation Code = 15 and return 5 results of "page" 2|
Search for IRS Foundation Code = 15 and return JSON format
MSA Code List
Subsection Code List
|200||OK, all went through!|
|401||Unauthorized, returned when the request requires user authentication. The response header will include WWW-Authenticate header realm "GuideStar Middleware API"|
|403||Forbidden, returned when the API understood the request, but is refusing to fulfill it. Most commonly, this means that the user has exceeded their request limit or does not have permissions to access this API.|
|404||There is an error in the URL string or the requested organization Id is not available.|
|500||Server Error, returned when the API encountered an unexpected condition which prevented it from fulfilling the request. A generic message (security reasons) will be displayed to the consumer but a detailed exception will be logged on API side.|
|503||Service Unavailable, returned when the API is unavailable to handle the request due to a temporary overloading or maintenance of the server. The existence of the 503 status code does not imply that we will be using it on a regular basis. It is here to cover rare cases only so that we can message and inform consumers if needed.|