Search Projects

This operation allows searching for projects using keywords. It is possible to request the project results in full or summary mode.

Search request with results in FULL mode:

https://api.globalgiving.org/api/public/services/search/project

Search request with results in SUMMARY mode:

https://api.globalgiving.org/api/public/services/search/project/summary

The search results can be filtered by a theme and/or country. The result set is limited to a maximum of 10 results for every request. If more than 10 results are required, adjust the &start query string parameter to paginate through the results. This is a non-secure request as indicated by the '/public/' element in the URL path, therefore, an access token (authentication) is not required.

HTTP Method:

GET

Content Type:

xml, json

Accept Type:

xml, json

Paths:

https://api.globalgiving.org/api/public/services/search/projects

or

https://api.globalgiving.org/api/public/services/search/projects/summary

Query String Parameters:

&api_key described in the API Key section, required

&q indicates the search query to use (must be URL encoded), required
Note: using a query value of * (ie. q=*) will get all projects based on any filter(s) provided

&start indicates the start position of the result set (defaults to 0), optional

&filter one or more key value pair separated by a colon indicating a filter to use and its value, for example, &filter=theme:edu or &filter=country:IN, optional
To have more than one filter, separate them by commas, for example: &filter=country:IN,theme=edu

Acceptable values for the country filter are the ISO 3166 country code identifiers for a specific country.

Acceptable values for the theme filter are the ones returned by the Get GlobalGiving Themes request.

Query String Example:

/api/public/services/search/projects?api_key=YOUR_API_KEY&q=pakistan+flood

tip

TIP: Projects returned from search only include projects where active = true
See Project Response Documentation

HTTP GET Request using cURL:

                  curl -H "Accept: application/xml" -H "Content-Type: application/xml" -X GET "https://api.globalgiving.org/api/public/services/search/projects?api_key=YOUR_API_KEY&q=pakistan+flood&filter=theme:disaster"
               

XML Response:

                  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
                  <search>
                      <request>
                          <filters>
                              <filter>
                                  <name>theme</name>
                                  <value>disaster</value>
                              </filter>
                          </filters>
                          <q>pakistan flood</q>
                          <start>0</start>
                          <summary>false</summary>
                      </request>
                      <response start="0" numberFound="16">
                          <projects>
                              <project>
                                  <active>true</active>
                                  <activities>it will provide income generating oppurtunity to 200 families. decrease poverty and reclusion, preparedness for flood calamity.</activities>
                                  <additionalDocumentation>http://cloud.globalgiving.org/pfil/5182/projdoc.doc</additionalDocumentation>
                                  <approvedDate>2010-04-14T15:16:56-07:00</approvedDate>
                                  <contactAddress>At. : Manikpur Musaharnia</contactAddress>
                                  <contactAddress2>P.O. – Andauli,</contactAddress2>
                                  <contactCity>District: Sitamarhi</contactCity>
                                  <contactCountry>India</contactCountry>
                                  <contactEmail>bgvpsitamarhi@gmail.com</contactEmail>
                                  <contactName>Ramachandra Rai</contactName>
                                  <contactPhone>91-9431426288</contactPhone>
                                  <contactPostal>843324</contactPostal>
                                  <contactState>Bihar</contactState>
                                  <contactUrl></contactUrl>
                                  <country>India</country>
                                  <donationOptions>
                                      <donationOption>
                                          <amount>50</amount>
                                          <description>provide one teal stall for a poor man</description>
                                      </donationOption>
                                      <donationOption>
                                          <amount>100</amount>
                                          <description>provide on cycle repairing materials to a poor man</description>
                                      </donationOption>
                                      <donationOption>
                                          <amount>150</amount>
                                          <description>provide one cycle rickshaw to a poor man for self living</description>
                                      </donationOption>
                                      <donationOption>
                                          <amount>8000</amount>
                                          <description>provide 1boat, 10 life jackets and 2 grain bank, 2 fodder banks, 100 chlorine tablets to 100 families for relief and rehabilitation</description>
                                      </donationOption>
                                      <donationOption>
                                          <amount>24750</amount>
                                          <description>Will fully fund this project</description>
                                      </donationOption>
                                  </donationOptions>
                                  <funding>0.00</funding>
                                  <goal>24750.00</goal>
                                  <id>5182</id>
                                  <imageGallerySize>17</imageGallerySize>
                                  <imageLink>http://cloud.globalgiving.org/pfil/5182/pict.jpg</imageLink>
                                  <image id="0">
                                      <imagelink size="small">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_grid1.jpg</url>
                                      </imagelink>
                                      <imagelink size="thumbnail">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_thumbnail.jpg</url>
                                      </imagelink>
                                      <imagelink size="medium">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_med.jpg</url>
                                      </imagelink>
                                      <imagelink size="large">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_grid7.jpg</url>
                                      </imagelink>
                                      <imagelink size="extraLarge">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_large.jpg</url>
                                      </imagelink>
                                      <imagelink size="original">
                                          <url>http://cloud.globalgiving.org/pfil/5182/pict_original.jpg</url>
                                      </imagelink>
                                      <title>The Image Title</title>
                                  </image>
                                  <iso3166CountryCode>IN</iso3166CountryCode>
                                  <longTermImpact>Income generation activity will lead to the economic empowerment, social security and stability.P reparedness for disaster lead to lesser impact of the disaster in coming years. More than 500 people will be benefitted by the relief and rehabilitation</longTermImpact>
                                  <need>Poverty, Reclusion, Health diability, lack of income generating oppurtunities, lack of sanitation are being faced by the villagers due to the occurence of flood</need>
                                  <numberOfDonations>0</numberOfDonations>
                                  <organization>
                                      <addressLine1>Village Manikpur, Musharnia, PO Andauli, District Sitamarhi</addressLine1>
                                      <city>Manikpur</city>
                                      <country>India</country>
                                      <id>2848</id>
                                      <name>Bihar Gram Vikas Parishad Sitamarhi</name>
                                      <postal>843324</postal>
                                  </organization>
                                  <progressReportLink>http://www.globalgiving.org/projects/flood-rehabilitation-relief-and-preparedness/updates/</progressReportLink>
                                  <projectLink>http://www.globalgiving.org/projects/flood-rehabilitation-relief-and-preparedness/</projectLink>
                                  <region>Asia and Oceania</region>
                                  <remaining>24750.00</remaining>
                                  <status>active</status>
                                  <summary>Relief and Rehabilitation of the Flood victims. Making the community prepared on flood Disaster and initiate income generating activity in the flood affected villages</summary>
                                  <themeName>Disaster Recovery</themeName>
                                  <title>Flood Rehabilitation: Relief and Preparedness</title>
                              </project>
                              .
                              .
                              <project>
                                 ......
                              </project>
                          </projects>
                      </response>
                  </search>
               

NOTE: The <project> child element of parent <projects> is repeating if more than one result is available.

Search Projects Response Structure

search
request
filters [zero or one]
filter [one or more]
name string
value string
q string
start int
summary boolean
response
start (attribute) int
numberFound (attribute) int
projects
project
see project response structure

Element Definitions for Search Projects Response

Element Mandatory Description
request -> filters -> filter -> name optional Name of the filter parameter provided, valid values: [theme, country].
request -> filters -> filter -> value optional The value of the filter parameter provided.
q required The "q" query string parameter, representing the keyword sent.
request -> start required The "start" query string parameter, representing where to start the result set.
summary required If "true", indicates the project results are being returned in Summary mode. If "false", indicates Full mode.
response -> start required Where the results are starting from.
response -> numberFound required The number of results found.
response -> projects -> project optional see element definitions for Get All Projects Response