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 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.
|q||The 'q' parameter is the main query for the request.|
|p||The '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".|
|r||The '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.|
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.
Request data for organization ID 7831216 with results in XML.
Request data for organization ID 7831216 with results in JSON format. (GuideStar QuickStart Detail - JSON Sample Results)
|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.|