API Specific Parameters

There are six parameters available specifically to this API:

APIKey (required)	Request a unique APIKey. You may also use DONORSCHOOSE for testing purposes.
callback (optional)	If you wish to wrap your response in a callback function, include the name here. You should make your callback static, as it will improve caching and in turn performance. (Many AJAX frameworks will make the callback a random string unless otherwise specified so you'll be overriding that default behavior.)
index (optional)	By default, the start index of the result set is 0; for example, by setting index=10 and max=10, you can return rows 10-19.
max (optional)	By default, the maximum number of projects returned is 10; you can request up to 50 rows at a time.
showSynopsis (optional)	To show the synopsis for each project listing set this to true.
showFacetCounts (optional)	To show facet counts set this to true. They will appear after the project listings. See the Facet Counts section in JSON Responses for more details.
showZeroFacetCountsForSchools (optional)	Facet counts will be displayed for all schools--including those with zero live projects--if this parameter is set to true and showFacetCounts is set to true and school counts are displayed because there is a community parameter in the search parameters. See JSON Responses > Facet Counts > Location for more details.

In addition, please include at least one search parameter, as described below.

Search Parameters

Note that search parameters are frequently updated; for the most up-to-date options, use DonorsChoose.org's Search Projects functionality as a starting point.

Keyword Search

Example:
http://api.donorschoose.org/common/json_feed.html?keywords="Canoga+Park"&APIKey=DONORSCHOOSE

In this example, we are searching for the phrase "Canoga Park."  To search for a phrase, enclose it in quotes. It gets a list of projects where the keyword search matches any of the following fields:

• id
• title
• synopsis (full length project essay; not returned in JSON)
• short description
• fulfillment trailer
• school name
• teacher's first name (not returned in JSON)
• teacher's last name (only initial returned in JSON)
• city
• county (not returned in JSON)
• district (not returned in JSON)
• ward/neighborhood (not returned in JSON)
• state (e.g. TX)
• zip (not returned in JSON)
• subject name

Subject

Example of searching for all Art & Music projects:
http://api.donorschoose.org/common/json_feed.html?subject1=-1&APIKey=DONORSCHOOSE

Example of searching for only Music projects:
http://api.donorschoose.org/common/json_feed.html?subject1=12&APIKey=DONORSCHOOSE

You can also search for subjects using keyword search. Here's an example of Music projects using keyword search:
http://api.donorschoose.org/common/json_feed.html?keywords=Music&APIKey=DONORSCHOOSE

A table of all the available subject fields and their associated parameters is below:

Music & The Arts Performing Arts Visual Arts Music	subject1=-1 subject1=1 subject1=11 subject1=12
Health & Sports Sports Health & Wellness Nutrition Gym & Fitness	subject2=-2 subject2=2 subject2=27 subject2=28 subject2=29
Literacy & Language Literacy Literature & Writing Foreign Languages ESL	subject6=-6 subject6=10 subject6=3 subject6=22 subject6=25
History & Civics History & Geography Civics & Government Economics Social Sciences	subject3=-3 subject3=9 subject3=13 subject3=14 subject3=15
Math & Science Health & Life Science Applied Science Environmental Science Mathematics	subject4=-4 subject4=4 subject4=6 subject4=7 subject4=8
Special Needs	subject7=-7
Applied Learning Early Development Community Service Character Education College & Career Prep Extra Curricular Parental Involvement Other	subject5=-5 subject5=18 subject5=21 subject5=26 subject5=16 subject5=17 subject5=20 subject5=19

Special Categories

Some Received Projects that have already received partial donations	partiallyFunded=yes
None Yet Projects that haven't yet received a donation	partiallyFunded=no
High Level of Poverty Projects from high need and high poverty schools (40% or more students receive free lunch)	highLevelPoverty=true
Never Before Funded Projects from teachers that have never had a project funded... yet	teacherNotFunded=true

Cost to Complete

$99 or less	costToComplete=1
$100-$200	costToComplete=2
$200-$1,000	costToComplete=3
$1,000-above	costToComplete=4

Cost to Complete Range

Example: costToCompleteRange=0+TO+400

Please note that when costToCompleteRange is set, costToComplete is ignored.

Resource Type

Books	proposalType=1
Technology	proposalType=2
Supplies	proposalType=3
Trips	proposalType=4
Visitors	proposalType=5
Other	proposalType=6
Trips & Visitors	proposalTypeCombo=Trips+%26+Visitors
Supplies	proposalTypeCombo=Supplies

Grade Level

Grades PreK-2	gradeType=1
Grades 3-5	gradeType=2
Grades 6-8	gradeType=3
High School	gradeType=4
Adult Ed	gradeType=5

Resource Usage

Essential	resourceUsage=1
Enrichment	resourceUsage=2

Teacher Type

Teach For America

teacherType=1

School Type

Charter School	schoolType=1
Magnet School	schoolType=4
Year Round School	schoolType=5

Challenges and Giving Pages

Example: challengeId=18369

Please note that, in contrast to the challenge page (http://www.donorschoose.org/donors/viewChallenge.html?id=18369), only projects that still need funding will be included in the JSON feed.

Matching Grant

Example: matchingId=6

Please use the "Match Offers" filter on our Search Projects page to get the matching grant value you need.

State or sub-state regions

State or sub-state region	State or metro code
Alabama	AL
Alaska	AK
Arizona	AZ
Arkansas	AR
California	CA
Colorado	CO
Connecticut	CT
Delaware	DE
Florida	FL
Georgia	GA
Hawaii	HI
Idaho	ID
Illinois	IL
Indiana	IN
Iowa	IA
Kansas	KS
Kentucky	KY
Louisiana	LA
Maine	MN
Maryland	MD
Massachusetts	MA
Michigan	MI
Minnesota	MN
Mississippi	MS
Missouri	MO
Montana	MT
Nebraska	NE
Nevada	NV
New Hampshire	NH
New Jersey	NJ
New Mexico	NM
New York	NY
North Carolina	NC
North Dakota	ND
Ohio	OH
Oklahoma	OK
Oregon	OR
Pennsylvania	PA
Rhode Island	RI
South Carolina	SC
South Dakota	SD
Tennessee	TN
Texas	TX
Utah	UT
Vermont	VT
Virginia	VA
Washington	WA
Washington D.C.	DC
West Virginia	WV
Wisconsin	WI
Wyoming	WY

To search by state code (e.g. TX) you can either do a keyword search or use the state parameter (e.g. state=TX).

You cannot search by metro code. We've included it as a reference as it might be helpful for geo-targeting scenarios since many IP-to-geo services will output metro codes.

Zip code

You can search by zip code using the keyword search field.

Community (city, county, district, or special)

Example: community=7%3a1

Please use the "Community" filter on our Search Projects page to get the community values you need. If you cannot find a particular city, county, or district through the Search Projects functionality, please contact us for help.

In some cities you can search by ward (e.g. Washington DC) or neighborhood (e.g. New York City, Chicago).

Please note that you can also use a keywords search to find projects in any community.

Finally, you can use the cityName parameter for city and the countyName parameter for county.

School

Example: school=472

Please use the Search Projects functionality to identify a specific school.

Also note that you can search by school name using a keywords search.

Sorting Options

You can sort your results by:

Urgency Shows projects with higher urgency at the top	sortBy=0
Poverty Shows projects from schools with the highest levels of poverty at the top	sortBy=1
Cost Shows projects with the lowest cost to complete at the top	sortBy=2
Popularity Shows projects with higher numbers of donors at the top	sortBy=4

Completed

The &historical=true parameter returns completed projects only. Without adding that parameter, the default behavior is to always return projects in need of funding.

An example of already-completed yoga-related projects: http://api.donorschoose.org/common/json_feed.html?keywords=yoga&historical=true&APIKey=DONORSCHOOSE

Geo Parameters

Geo: Lat/Long Data

You will get latitude and longitude values accompanying each project in all JSON responses. No additional request parameters are needed to prompt the inclusion of the lat/long data.

Geo: "Bounding Box" Searches

You can specify the northwest and southeast corners of a geographic area to request projects posted from classrooms located within the specified geographic "bounding box."

Specify the NW point using the parameters nwLat and nwLng. Specify the SE point using seLat and seLng.

An example of projects within the area bounded by the NW point 40.776104/-73.920822 and the SE point 40.632437/-73.797226: http://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&nwLat=40.776104&nwLng=-73.920822&seLat=40.632437&seLng=-73.797226

Geo: "Center + Distance" Searches

You can also specify the center plus a radius of a geographic area to request projects posted from classrooms located within the specified circular geographic region.

Specify the center point using the parameters centerLat and centerLng. Specify the radius using radius.

An example of projects within the area within 50 miles of the point 40.776104/-73.920822: http://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&centerLat=40.776104&centerLng=-73.920822&radius=50

Geo: "Projects Near Me" Searches

You can also specify the center without a radius and the system will return at least 25 results near the specified point (if there are 25 projects that match the other criteria in the search). Note that if "max" is not specified then there will be only 10 projects returned.

Specify the center point using the parameters centerLat and centerLng. Leave out the "radius" parameter.

An example of projects near the point 40.776104/-73.920822: http://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&centerLat=40.776104&centerLng=-73.920822

Large result sets

If you are plotting potentially many points on a map, we recommend you use add the &concise=true parameter to your JSON request. This feature reduces the amount of per-project info returned in the JSON response to only 4 fields which greatly accelerates the speed with which we can return you large result sets.

Including the &concise=true parameter also raises the per-request maximum to 1,000 projects which is especially useful for plotting points on a map.

An example of (up to 1,000) Art & Music projects the concise format: http://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&subject1=-1&concise=true

An example of (up to 1,000) projects within the area bounded by the NW point 40.776104/-73.920822 and the SE point 40.632437/-73.797226: http://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&nwLat=40.776104&nwLng=-73.920822&seLat=40.632437&seLng=-73.797226&concise=true

We'll first need to enable your API key for extra large responses. Get in touch with us to get an enabled API key.