Note to API Users:

This page provides details about the first generation GuideStar APIs, for which the calling URL is https://data.guidestar.org 

GuideStar has released a Next Generation of APIs. The earlier APIs, which are discussed here, are no longer available for purchase. For more information about the new APIs, and to request a free trial subscription, use the link: https://learn.guidestar.org/products/business-solutions/guidestar-apis. The "Free Trial" request link can be found at the bottom of the page.

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.

GuideStar Generation I Production APIs

GuideStar Production APIs are subscription-based, and include:

  • CharityCheck,
  • CharityCheck PDF,
  • Detail,
  • Exchange (Profile Update Program data),and Search.

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.

Requests

Example: https://data.guidestar.org/v3/charitycheck/{EIN}.{xml/json}

Description: 

https://data.guidestar.org/v3/charitycheck/54-1774039.xml

  • Request CharityCheck API information for GuideStar (EIN 54-1774039) with results in XML.

https://data.guidestar.org/v3/charitycheck/54-1774039.json

  • Request CharityCheck API information for GuideStar (EIN 54-1774039) with results in a JSON format.

Available Fields

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. 

Requests

Example: https://data.guidestar.org/v3/charitycheck/PDF/{EIN}

Description:

https://data.guidestar.org/v3/charitycheck/pdf/54-1774039

  • Request CharityCheck API PDF Document for GuideStar (EIN 54-1774039)

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.

Requests

Example: https://data.guidestar.org/v3/exchange/{OrganizationID}.{xml/json}

Description:
https://data.guidestar.org/v3/exchange/7831216.xml

  • Request Exchange API data for organization ID 7831216 with result in XML. 

https://data.guidestar.org/v3/exchange/7831216.json

  • Request Exchange API data for organization ID 7831216 with result in JSON format.

Available Fields

GuideStar Detail API

The GuideStar Detail API combines nonprofit-supplied information with data from other sources to provide comprehensive information about millions of organizations.

Requests

Example: https://data.guidestar.org/v1/detail/{OrganizationId}.{xml/json}

Description:

https://data.guidestar.org/v1/detail/7831216.xml 

  • Request Detail API data for GuideStar (organization ID 7831216) with result in XML. 

https://data.guidestar.org/v1/detail/7831216.json

  • Request Detail API data for organization ID 7831216 with result in JSON format. 

Available Fields

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

The GuideStar Search V1_1 API now include a zip code radius search capability.

Here are some examples of how to make basic calls using the GuideStar Search API, and examples of how to call Search using the Radius Search feature: 

Parameters

Parameter q: 

  • The 'q' parameter is the main query for the request.

Parameter 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. 

Parameter r:

  • 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.

Zipcode:

  • The 'zipcode' parameter specifies the center zip code for a radius search, and works in tandem with the radius parameter to search a given area for organizations that are in the particular zip code and a radius surrounding that zip code. The zipcode parameter requires a keyword search parameter, such as "cancer" or "education" before adding the zipcode and radius filters to the query. To search all organizations in a zipcode/radius range, use the Lucene syntaxq=*:*&{zipcodevalue}&{radius value} The'q=*:*' part of the query specifies all organizations that have all values.The zipcode and radius parameter filter the set of all organizations 

Radius:

  • The 'radius' parameter is an integer parameter that specifies the number of miles surrounding the given zipcode in which to search for organizations. In general, increasing the radius value will increase the number of organizations found. The maximum value for radius is 25 mile. The minimum value corresponds to the size of the are specified by the zipcode value. In New York City, for example, a zip code may cover a mile or two. In some more rural areas, a zip code may cover a larger area. The radius value may be as little as 1, but in most cases a value of 1 will return the same list of organization as a radius of 2 does, since most zip codes cover an area of more than a mile in size. 

Requests

Example                                                                Description

https://data.guidestar.org/v1_1/search?               Search for an organization with an EIN
q=ein:54-1774039
                                                = 54-1774039

https://data.guidestar.org/v1_1/search?               Search for all organizations with an IRS
q=irs_foundation_code:15                                   Foundation Code = 15
                                                                               (Foundation Code Sample Results) 

https://data.guidestar.org/v1_1/search?               Search for IRS Foundation Code = 15
q=irs_foundation_code:15&p=2                           and return "page" 2 of the result

https://data.guidestar.org/v1_1/search?               Search for IRS Foundation Code = 15
q=irs_foundation_code:15&r=5                           and return 5 results

https://data.guidestar.org/v1_1/search?               Search for IRS Foundation Code = 15
q=irs_foundation_code:15&p=2&r=5                  and return 5 results of "page" 2

https://data.guidestar.org/v1_1/search.json?
     Search for IRS Foundation Code = 15
q=irs_foundation_code:15                                   and return JSON format                                                                                                         (Foundation Code Sample Results
                                                                               JSON Format)

https://data.guidestar.org/v1_1/search.json?     Search for organizations involved in
 q=education&zipcode=23188&radius=10         education that have addresses in
                                                                              the 23188 zip code and within a radius
                                                                              of 10 miles around that zip code. Note
                                                                              that a double or real datatype with a
                                                                              fractional component (e.g., 5.20) does
                                                                              not work. Return JSON format (Sample
                                                                              Results:Education Organizations in a 10
                                                                              mile radius around zip code 20001)
https://data.guidestar.org/v1_1/search.json?     Search for all organizations that have
q=*:*&zipcode=23188&radius=10                       addresses in the 23188 zip code and
                                                                             within a radius of 10 miles around that
                                                                             zip code.Return JSON format(Results for
                                                                             Radius Search - All organizations 25                                                                                    miles around zipcode 20001

Available Fields

MSA Code List

Advanced Search API MSA Code List

Subsection Code List

Advanced Search API Subsection Code List

Return Codes


      

Did this answer your question?