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:

Search request with results in SUMMARY mode:

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:

or

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:

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>https://www.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>https://www.globalgiving.org/pfil/5182/pict.jpg</imageLink>
                <image id="0">
                    <imagelink size="small">
                        <url>https://www.globalgiving.org/pfil/5182/pict_grid1.jpg</url>
                    </imagelink>
                    <imagelink size="thumbnail">
                        <url>https://www.globalgiving.org/pfil/5182/pict_thumbnail.jpg</url>
                    </imagelink>
                    <imagelink size="medium">
                        <url>https://www.globalgiving.org/pfil/5182/pict_med.jpg</url>
                    </imagelink>
                    <imagelink size="large">
                        <url>https://www.globalgiving.org/pfil/5182/pict_grid7.jpg</url>
                    </imagelink>
                    <imagelink size="extraLarge">
                        <url>https://www.globalgiving.org/pfil/5182/pict_large.jpg</url>
                    </imagelink>
                    <imagelink size="original">
                        <url>https://www.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>https://www.globalgiving.org/projects/flood-rehabilitation-relief-and-preparedness/updates/</progressReportLink>
                <projectLink>https://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

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