GuideStar Next Generation API Frequently Asked Questions

Document created by communitymanager Administrator on Jan 18, 2018Last modified by JackCowardin on Jun 20, 2018
Version 10Show Document
  • View in full screen mode

Frequently Asked Questions

The GuideStar APIs are RESTful. They are simple, predictable, and use standard HTTP response codes to indicate status and errors. We also use standard HTTP verbs, which are understood by all HTTP clients. All of our APIs return responses in JSON format.

 

For users requiring XML return data, there are numerous conversion utilities available on the web.

 

What are the GuideStar Next Generation APIs?

The GuideStar Next Generation APIs offer 3 services to meet the data needs of customers. They are:

  • The Essentials API – Essentials is an Elastic Search-based API that provides a search function that duplicates the Search available on GuideStar.org and provides a summary of each nonprofit.
  • The CharityCheck API – CharityCheck provides the latest data regarding the tax-exempt status of every nonprofit organization in the GuideStar database. There are three distinct services offered in the Charity Check API set, including an PDF API that allows users to create a PDF to save, file, or print and a Bulk Charity Check API that allows users to Charity Check hundreds of nonprofits at a time.
  • The Premier API – The Premier API offers comprehensive data that corresponds to the data found on GuideStar.org, including Summary, Programs, Financials, and Operations data. A Premier Subscription includes the Essentials API and returns Charity Check data.

 

Are the Next Generation APIs direct drop-in replacements for the original REST APIs? Will our old implementation of your APIs still work?

No, the GuideStar Next Generation APIs use a Microsoft Azure host and a new key-based authentication mechanism. The Essentials Search is no longer based on Lucene, but uses the Elastic Search Engine and matches the architecture and results of the www.guidestar.org/search

 

The root URL for the Next Generation APIs is also new.

 

How does the Next Generation API Search using Essentials differ from the original REST Search API?

 The GuideStar Essentials API (Elastic-based) is more structured than the Lucene-based Search API. A primary goal is to ensure that Search API results match the search results that are found on the GuideStar.org website.

 

While the last generation of APIs allowed free-form, keyword, and field-specific searching, the Next Generation of APIs also allows free-form searching, but utilizes a JSON search query construct that is submitted in the HTTP GET that makes up the request. The JSON query allows filters to be used in addition to free-form search terms. These include filters for geographic, NTEE, IRS Subsection, and other filters.

 

Can I search the Essentials API using the GuideStar Organization ID?

 The GuideStar Organization ID (organization_id in API return data) is an internal identifier employed in the GuideStar databases. It allows GuideStar to differentiate organizations that may share the same EIN, as occurs when parent organizations have subordinate organizations that share a Federal EIN. This value is subject to change. Although a change to an organization ID is rare, it can occur and so this value should not be stored as an identifier in external systems. Therefore, organization ID is not allowed as a search term in the Essentials API.

 

What are the best terms to use to search using the Essentials API?

The Essentials API requires, at a minimum, a “search term” supplied in JSON format. For example, an organization’s Federal Employer Identification Number (EIN) can be used, as in

 

search_terms 
     {
         “54-1774039
     }

 

A free form term can also suffice as a very simple JSON search payload for Essentials

 

search_terms 
    {
        “cancer”
    }

 

For other search criteria, use the filters provided to limit result sets as in the example here: https://apiportal.guidestar.org/api-static-documentation-v1

 

 

What is the Premier API?

The Premier API delivers a large result that includes the data that can be found using the GuideStar.org website at https://www.guidestar.org.

 

The Premier API is called using the Organization ID, an internal GuideStar identifier. The Organization ID is returned by the Essentials API as the result of a call to that API. Search by organization name, EIN, or using one of the filters provided in the Essentials search. Take the organization_id returned in the search results and use this to invoke the Premier API and receive comprehensive and complete data about any nonprofit that is in the GuideStar database.

 

Where can I find coding examples that show how to use the GuideStar APIs?

The GuideStar API Developer Portal https://apiportal.guidestar.org provides documentation for the APIs. Additionally, there are dynamic pages where you can try the APIs without writing any code at https://apiportal.guidestar.org/products.

Click on the name of API you wish to try.

 

A simple C# console application code example is here: https://github.com/GuideStar/Profile_API_Example

 

The GuideStar Community is a place where further information can be found, and where you can post questions to the user community and to GuideStar support engineers.

 

To sign up for free trial licenses, visit GuideStar APIs.

 

How is the Premier API queried?

The Premier API takes as a parameter the Organization ID of the organization you are researching. The Organization ID is a GuideStar specific identifier that is found using the Essentials API. Essentials can be searched using a free text search term, the organization’s EIN, or using any one of the filters provided—Geography, NTEE Codes, IRS Subsection, etc.

 

 

What are the limits to the number of calls that can be made to the APIs?

GuideStar offer a Free Trial versions of each Next Generation API that allow up to 500 API calls per 60-day period. The maximum rate for these calls is 10 per minute. These are available for a period of 60 days but can be extended for longer period. Contact a sales representative for an extension. The Free Trial APIs include the Essentials, CharityCheck and CharityCheck PDF, and Premier APIs

 

The licensed APIs START at the following limits:

  • GuideStar Essentials API: up to 12,000 calls annually
  • GuideStar CharityCheck API: up to 2,500 calls annually
  • GuideStar Premier API (includes Essentials and Charity Check data): up to 12,000 calls annually.

 

What are the “throttling limits” for GuideStar APIs?

GuideStar “throttles” API calls to protect all API users so that no single API client can dominate the available bandwidth for calls and thus reduce access for other API customers. The Free Trial APIs are throttled at a rate of 10 calls allowed per minute. Licensed API calls are throttled at a higher rate of 120 calls per minute. Throttling is not the same as a quota, which is applied as a limit to the number of calls that may be made monthly or annually.

 

What is the guaranteed uptime?

GuideStar partners with Microsoft Azure to guarantee 99.9% uptime.

 

How do I access the API Sandbox?

The original Sandbox APIs have been replaced by a Free Trial product that offers limited access to the current GuideStar APIs. The Free Trial allows up to 250 calls per month for any of the APIs. These Free Trial products require registration and the assignment of an API key. Sign up for the Free Trial APIs. Click the "Free Trial" button at the bottom of the page.

 

What is the difference between the 3 CharityCheck API options?

The CharityCheck API has 3 variants.

  • The basic CharityCheck API takes an organization’s EIN as a parameter and returns tax exempt status information about that organization.
  • The CharityCheck PDF API returns a binary data stream that can be stored and rendered as a PDF document.
  • The CharityCheck Bulk API takes as input a JSON structure that lists multiple (up to 20) comma-separated organization EINs. It returns a list of CharityCheck reports, one for each EIN specified. Here is a sample JSON for input to the CharityCheck Bulk API:

 

{
   "eins": [
             "54-1774039"
             "13-1644147"
             "43-0718808"
           ]
}

 

 

Why are Logo URLs available in the Search API but not in the Essentials API?

The next generation search, powered by the Essentials API, gives the user a search experience which aligns with the https://www.guidestar.org Pro search experience. The GuideStar Mainsite does not require a display of the logos in the search results page so the data field was never part of an index we currently use. We recognize that losing Logo URL was one of the compromises we had to make to better align our technologies, search capabilities, and results in the next generation APIs.

 

Why do I have both a Primary and a Secondary Key?

It is not a scenario often encountered, but if a primary API key for a subscription became compromised, or needed to be retired, the secondary key provides the opportunity to smoothly transition to a new key. Without the secondary key there would be a period between the regeneration of the primary key and the time an application could be updated to use the new key.  During this period the API calls would not work. The primary and secondary API keys both work for the single URI.

 

An example of a time when a secondary key might be useful is if a contract developer, who has been using the primary key, completes a development project and you need to end their access to the API subscription.

The GuideStar Developer Portal

GuideStar Developer Portal 

API Pricing & Free Trials

APIs Pricing 

What if my question wasn't answered here?

Create a support case.

Attachments

    Outcomes