GuideStar APIs

Document created by communitymanager Administrator on Dec 10, 2015Last modified by JackCowardin on Oct 30, 2017
Version 68Show Document
  • View in full screen mode

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,
  • CharityCheck PDF,
  • Detail,
  • Exchange (Profile Update Program data)
  • and Search.

(described below)

 

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

 

 

API Code Examples

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.

Example Data Classes for API Return Data

Use these classes to hold deserialized API data

 

Note About Using GuideStar API Keys - Authentication

What is an API Key? Why and how should I use one?

 

Note about calling GuideStar APIs from Javascript or other client-side scripting.

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.

 

Requests

ExampleDescription
https://data.guidestar.org/v3/charitycheck/{EIN}.{xml/json}https://data.guidestar.org/v3/charitycheck/54-1774039.xml 


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

GuideStar Charity Check API XML Results

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


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

GuideStar Charity Check API JSON Sample Results

Available Fields

  • organization_info_last_modified
  • ein
  • organization_id
  • organization_type_2
  • organization_name
  • organization_name_aka
  • addressline_1
  • addressline_2
  • city
  • state
  • state_name
  • zip
  • charity_check_last_modified
  • pub78_organization_name
  • pub78_ein
  • pub78_verified
  • pub78_city
  • pub78_state
  • organization_type_1
  • deductibility_limitation_1
  • pub78_indicator
  • deductibility_status_description_code_1
  • organization_type_1
  • deductibility_limitation_1
  • deductibility_status_description_code_2
  • organization_type_2
  • deductibility_limitation_2
  • deductibility_status_description_code_3
  • organization_type_3
  • deductibility_limitation_3
  • deductibility_status_description_code_4
  • organization_type_4
  • deductibility_limitation_4
  • deductibility_status_description_code_5
  • organization_type_5
  • deductibility_limitation_5
  • deductibility_status_description_code_6
  • organization_type_6
  • bmf_subsection
  • subsection_description
  • deductibility_limitation_6
  • deductibility_status_description_code_7
  • organization_type_7
  • deductibility_limitation_7
  • most_recent_pub78
  • most_recent_irb
  • bmf_organization_name
  • bmf_ein
  • bmf_status
  • most_recent_bmf
  • foundation_code
  • foundation_code_description
  • ruling_month
  • ruling_year
  • adv_ruling_month
  • adv_ruling_year
  • group_exemption
  • exemp_status_code
  • ofac_status
  • revocation_code
  • revocation_date
  • reinstatement_date
  • irs_bmf_pub78_conflict
  • foundation_509a_status
  • irb_organization_id
  • bulletin_number
  • bulletin_url
  • effective_date
  • irb_last_modified

 

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:

Web Service To REST API Conversion - CharityCheck PDF Example 

 

Requests

 

 

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

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


Request Exchange API data for organization ID 7831216 with result in XML. (GuideStar Exchange API XML Sample Results)

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


Request Exchange API data for organization ID 7831216 with result in JSON format.(GuideStar Exchange API JSON Sample Results)

 

Available Fields

  • GuideStar Organization ID
  • EIN (Government issued ID)
  • Bridge ID
  • Primary Organization Name
  • AKA Name
  • Doing Business As
  • Formerly Known As (list)
  • Doing Business As
  • Government Registered Name
  • IRS Subsection Code
  • IRS 509a Status
  • Organization Logo Url
  • Logo Name
  • Government Issued Ruling Year
  • Year Founded
  • Incorporation Year
  • Keywords
  • Mission Statement
  • Geographic Areas Served (list)
  • Geographic Areas Served Narrative
  • Impact Statement
  • CEO Comments
  • GuideStar Profile Level
  • Primary Telephone
  • Fax
  • International Telephone
  • Primary Address
  • Physical Address
  • International Address
  • Website URL
  • Blog URL
  • Social media URLs
  • Organization Email
  • NTEE Codes (list)
  • Fiscal Year Start
  • Fiscal Year End
  • Contributions Gifts and Grants
  • Program Service Revenue
  • Membership Dues
  • Net Income from Special Event
  • Total Revenue
  • Program Expenses
  • Description of Other Revenue
  • Amount of Other Revenue
  • Administration Expenses
  • Fundraising Expenses
  • Payments to Affiliates
  • Description of Other Expense
  • Amount of Other Expense
  • Total Expenses
  • Total Assets
  • Total Liabilities
  • Net Assets End of Year
  • Primary Contact
  • Executive Director
  • CoExecutive Director
  • Board Chair
  • Board CoChair
  • Board Members (list)
  • Senior Staff (list)
  • Letter of Determination document
  • Letter of Dissolution document
  • Other Staff (list)
  • Programs (list)
  • Financial Statement documents (list)
  • Annual Report documents (list)
  • Form 990 documents (list)
  • Form 990T documents (list)
  • Form 1023/1024 documents (list)
  • Other documents (list)
  • Funding Sources (list)
  • Funding Needs (list)
  • Accreditations (list)
  • Awards (list)
  • Affiliations (list)
  • Charting Impact Answers
  • Videos (list)
  • Photos (list)
  • Notes
  • Board Source Answers
  • Demographics Details

 

 

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

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


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

GuideStar Detail API XML Sample Results

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


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

GuideStar Detail API JSON Sample Results

 

Available Fields

  • GuideStar Organization ID
  • EIN
  • Organization Name
  • Address Line 1
  • Address Line 2
  • City
  • State
  • Zip + 4
  • Affiliation Code and Description
  • AKA Name
  • Total Assets
  • Contact Fax
  • Contact Phone
  • Deductibility Code and Description
  • Total Expenses
  • Foundation Code and Description
  • Group Exemption
  • Total Income
  • IRS Subsection Code and Description
  • National Headquarters Indicator
  • Total Liabilities
  • Mission Statement
  • Geographic Areas Served (list)
  • Telephone
  • Link to organization's public report on GuideStar's website
  • Ruling Year
  • Tax Year
  • Website url
  • Year Founded
  • NTEE Codes (list)
  • Total Revenue
  • CEO and Co-Ceo
  • Programs (list)

 

 

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.

 

New

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

Find details here: New Zip Code Radius search in GuideStar Search V1_1 API 

 

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

ParameterExplained
qThe 'q' parameter is the main query for the request.
pThe '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.
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 syntax

q=*:*&{zipcode value}&{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

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

Search for all organizations with an IRS Foundation Code = 15

(Foundation Code Sample Results)

https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2Search 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=5Search for IRS Foundation Code = 15 and return 5 results
https://data.guidestar.org/v1_1/search?q=irs_foundation_code:15&p=2&r=5Search for IRS Foundation Code = 15 and return 5 results of "page" 2
https://data.guidestar.org/v1_1/search.json?q=irs_foundation_code:15

Search for IRS Foundation Code = 15 and return JSON format

(Foundation Code Sample Results JSON Format)

New!!

https://data.guidestar.org/v1_1/search.json?q=education&zipcode=23188&radius=10

Search for organizations involved in 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 data type 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)

New!!

https://data.guidestar.org/v1_1/search.json?q=*:*&zipcode=23188&radius=10

Search for all organizations that have 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 zip code 20001)

GuideStar Search API Technical Notes 

Search API 1_1 Zip Code Search Results Example 

Combining multi-word Lucene Search terms in GuideStar Search V1_1 API 

 

Available Fields

  • organization_id
  • ein
  • organization_name
  • mission
  • city
  • state
  • zip
  • nteecode
  • participation
  • public_report
  • irs_subsection
  • irs_foundation_code
  • msa
  • logo_url
  • national_hq
  • website
  • parents
  • bmf
  • pub78
  • revocation
  • organization_name_aka
  • online_giving_flag
  • gs_donation_optin

 

MSA Code List

Advanced Search API MSA Code List

Subsection Code List

Advanced Search API Subsection Code List

 

 

Return Codes

ErrorExplained
200OK, all went through!
401Unauthorized, returned when the request requires user authentication. The response header will include WWW-Authenticate header realm "GuideStar Middleware API"
403Forbidden, 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.
404There is an error in the URL string or the requested organization Id is not available.
500Server 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.
503Service 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.

Attachments

    Outcomes