GuideStar QuickStart Data API

Document created by communitymanager Administrator on Feb 26, 2016Last modified by JackCowardin on Feb 8, 2017
Version 22Show Document
  • View in full screen mode

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:

  • The QuickstartSearch API allows keyword and wildcard searches.
  • The 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.

 

Important notes about the QuickStart APIs...

  • The QuickStart APIs, while offered at no charge, require a user license for authentication. Contact GuideStar to receive a free license and API key for accessing the QuickStart APIs. 
  • The QuickStart Search API is functionally equivalent to the GuideStar Production Search API. However, it uses a slightly more exclusive filtering mechanism than the Production V1_1 Search. Therefore certain organizations that will be returned by the Production Search V1_1 will not be returned by the QuickStart Search.

 

 

GuideStar QuickStart Code Samples

 

Notes About Using GuideStar API Keys - Authentication

  

GuideStar QuickStart Search

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

Here is the information specific to the GuideStar Quickstart Search and some examples on how to make basic calls.

Parameters

ParameterExplained
qThe 'q' parameter is the main query for the request.
pThe 'p' parameter is used to paginate results from a query. When specified, it indicates the offset in the complete result set for the queries where the set of returned documents should begin. The default value is "1".
rThe 'r' parameter specifies the number of Nonprofit Organizations (NPOs) returned on each page for values of 1 through 25. The default is 10 NPOs per page.

Requests

ExampleDescription
https://quickstartdata.guidestar.org/v1/quickstartsearch?q=ein:54-1774039Searching for an organization with an EIN = 54-1774039
https://quickstartdata.guidestar.org/v1/quickstartsearch?q=zip:23188

Searching for all organizations with zip code = 23188

(QuickStart Search - Zip Code Sample Results)

https://quickstartdata.guidestar.org/v1/quickstartsearch?q=giving

or

https://quickstartdata.guidestar.org/v1/quickstartsearch?q=keyword:giving
Searching for a keyword "giving"
https://quickstartdata.guidestar.org/v1/quickstartsearch?q=giving&p=2Searching for a keyword "giving" and return "page" 2 of the result
https://quickstartdata.guidestar.org/v1/quickstartsearch?q=organization_name:conservation&p=5&r=5Searching for a keyword "convervation" in the organization name and return "page" 5 of the result where there are 5 NPOs per page.
https://quickstartdata.guidestar.org/v1/quickstartsearch.json?q=givingSearching for a keyword "giving" and return the result in JSON format
https://quickstartdata.guidestar.org/v1/quickstartsearch.xml?q=organization_name:guide*Wildcard searching for an organization name having "guide*" and return the result in XML format
https://quickstartdata.guidestar.org/v1/quickstartsearch.json?q=organization_name:guide*

Wildcard searching for an organization name having "guide*" and return the result in JSON format.

(QuickStart Search - Wildcard JSON Sample Results)

Available Fields

  • organization_id
  • organization_name
  • ein
  • city
  • state
  • zip
  • participation
  • public_report

GuideStar QuickStart Detail

The Detail API uses Organization ID to deliver data about an organization. Use the QuickStart Search API to find the organization ID for a given EIN.

 

Requests

Available Fields

  • organization_id
  • ein
  • organization_name
  • address
  • city
  • state
  • zip
  • zip4
  • affiliation_code
  • affiliation_code_description
  • aka_organization_name
  • deductibility_code"1"
  • deductibility_code_description
  • foundation_code
  • foundation_code_description
  • group_exemption
  • income_total
  • subsection_code
  • subsection_code_description
  • mission
  • retrieval_time

Return Codes

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

3 people found this helpful

Attachments

    Outcomes