Note to API Users:

This page provides details about the first generation GuideStar APIs, for which the calling URL is:

http: //data.guidestar.org/{version}/{api name}/{organization EIN or Organization ID}

GuideStar has released a next generation of the REST APIs.For more information about the GuideStar Next Generation APIs, and to request a free trial subscription, use this link:

https: //learn.guidestar.org/products/business-solutions/guidestar-apis.

The "Free Trial" request link can be found at the bottom of the page.

1. Connect to the API using cURL

curl -3 -u username:password https://data.guidestar.org/v1_1/search?q=ein:54-1774039

2. Connect to the Search v.1_1 API using C# .NET

usingSystem;
usingSystem.Collections.Generic;
usingSystem.Linq;
usingSystem.Text;
usingSystem.Threading.Tasks;
usingSystem.Net;
usingSystem.IO;
usingSystem.Diagnostics;
namespaceC# API_Example

  {

      classProgram

      {
            static void Main(string[]args)

            {   / /  Call the Search API and get information for the Organization with EIN =
                / /  54-1774039 

               req.Proxy =null;
               var  response = req.GetResponse();
               using  (Stream dataStream = response.GetResponseStream( ) )
                {
                   using(StreamReader reader = new StreamReader (dataStream) )

                   {
                             string  responseFromServer  =   reader.ReadToEnd( );
                             Console.WriteLine(responseFromServer) ;
                   }

               }
              Console.ReadKey( );
              response.Close( );
        }
    }
}

3. Connect to the Search v.1_1API using Java

This example makes use of the Apache HttpClient library 4.1 to simplify http requests. To use this library, download the binaries with dependencies from http://hc.apache.org/ and add them to your project class path. Include your GuideStar credentials in place of the user:password.

package org.guidestar.data.api;
import java.io.IOException;
import org.apache.http.HttpEntity;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import org.apache.commons.codec.binary.Base64;
public class TestAPI {
           //this is the request string that calls the search API.
          //Search for Organizations in the 23188 zip code and return 25 results.

          private static String request = "https://data.guidestar.org/v1/search?      
          q=zip:23188&r=25";

          public static void main(String[] args) throws ClientProtocolException,
          IOException
          {
                      //encode login credentials
                     byte[] encodedBytes = Base64.encodeBase64(username + ":" +    
                     password.getBytes());
                     //The recommended httpclient to use.
                    CloseableHttpClient httpclient = HttpClients.createDefault();
                    HttpGet httpget = new HttpGet(request);
                    //Set the authorization header with the GuideStar API credentials
                   httpget.setHeader("Authorization","Basic " + new String(encodedBytes));
                   //The recommended response object to use.
                  CloseableHttpResponse response = httpclient.execute(httpget);
                 //We want to try and get an entity back from the response to our request try
                {
                            HttpEntity entity = response.getEntity();
                            if (entity != null)
                            {
                             System.out.println(EntityUtils.toString(entity));
                             }
                }
                catch(Exception e)
                {
                          e.printStackTrace();
                }
                finally
                {      //close the response object and client object
                            response.close();
                            httpclient.close();
                }
        }

}

4. Connect to the CharityCheck v. 3 API using Ruby

require 'net/http'
uri = URI('https://data.guidestar.org/v3/charitycheck/54-1774039')
Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https', :verify_mode => OpenSSL
::SSL::VERIFY_NONE) do |http|
request = Net::HTTP::Get.new uri.request_uri
    request.basic_auth 'username', 'password'
response = http.request request # Net::HTTPResponse object
puts response.body
end

5. Connect to the Search v.1_1API using PHP

Copy the code below into a .php file. Add your authentication information (username and password, or API key with a blank password) and call the code from a PHP-enabled browser.

<!DOCTYPE html>

<html>  <body>

<h1>PHP GuideStar Search API Test</h1>

<?php
// call the GuideStar Search v 1_1 API and search on the term "guidestar".
// Specify the return results to be delivered in JSON format.
$url = 'https://data.guidestar.org/v1_1/search.json?q=guidestar';
// alternate API calls...
//$url = 'https://data.guidestar.org/v3/charitycheck/54-1774039.json';
//$url = 'https://data.guidestar.org/v3/Exchange/54-1774039.json';
echo '<h2>URL:==> '.$url."</h2>";
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
//Set options required by HTTPS
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
curl_setopt($curl, CURLOPT_USERPWD, ":");
curl_setopt($curl , CURLOPT_SSL_VERIFYPEER , false );
curl_setopt($curl , CURLOPT_SSL_VERIFYHOST , false );
$output = curl_exec($curl);
if (curl_errno($curl))
{
echo 'Curl Error: ' .curl_error($curl);
$info = curl_getinfo($curl);
curl_close($curl);
die('error occured during curl exec. Additional info: ' . var_export($info));
}
curl_close($curl);
print "Decoded JSON:<br>";

//JSON decoding in PHP only works for UTF-8 encoded text

$decoded = json_decode($output, true ); if(json_last_error() != JSON_ERROR_NONE) switch (json_last_error())
{
     case JSON_ERROR_NONE:
         echo ' - No errors';
     break;
     case JSON_ERROR_DEPTH:
        echo ' - Maximum stack depth exceeded';
     break;
     case JSON_ERROR_STATE_MISMATCH:
         echo ' - Underflow or the modes mismatch';
     break;
     case JSON_ERROR_CTRL_CHAR:
         echo ' - Unexpected control character found';
     break;
     case JSON_ERROR_SYNTAX:
         echo ' - Syntax error, malformed JSON';
     break;
     case JSON_ERROR_UTF8:
         echo ' - Malformed UTF-8 characters, possibly incorrectly encoded';
     break;
     default:
         echo ' - Unknown error';
     break;
}

// The JSON return data may include nested arrays. In the Search API, the search "hits"
// are themselves an array, so we process the result using a recursive function that will
// display nested arrays to any depth.
printNestedArray($decoded);
echo '<br>response ok!';
// Echo each key:value in the array. If the 'value' is an array,
//call the function recursively
function printNestedArray($a)
{
    echo '<blockquote>';
    foreach ($a as $key => $value)
    {
       echo htmlspecialchars("$key: ");
       if (is_array($value))
       {
           printNestedArray($value);
       }
       else
       {
          echo htmlspecialchars($value) . '<br/>';  
       }
}
echo '</blockquote>';   }
?>
</body>
</html>

Did this answer your question?