USA Web Children Search

The USA Web Children Search API is a RESTful API.

The service returns a list of children matching specified criteria that are currently available on the Compassion.com website. The children on the Compassion.com website are a subset of all the children available for sponsorship from Compassion International.

By default, the service will return 20 children but accepts a take parameter to select a specific number of children up to the maximum 100. This service also supports a skip parameter, which can be used in conjunction with take to build paginated interfaces.

Please see Available Criteria to see the list of available parameters that can be used to filter the results. Additionally, a sort parameter can be used to determine the order in which the children are sorted (“random” is a possible sort order, but it is not useful for paginating with skip/take).

Sample Requests

These are just examples and are not intended to be comprehensive.

https://webapi.compassion.com/children/search?name=Jose&api_key=[string]
https://webapi.compassion.com/children/search.json?countryList=MX,DO&gender=M&api_key=[string]
https://webapi.compassion.com/children/search.json?region=Africa&birthMonth=2&api_key=[string]

Request Parameters

NameDescriptionRequiredData TypeConstraints
Name Querystring Parameter. Part or all of a child’s name. This will search through both the “ChildName” and “ChildPersonalName” fields. Optional Numeric Case-insensitive
Gender Querystring Parameter.Gender filter. Optional String F or M
CountryList Querystring Parameter. Comma-delimited list of two-character ISO country codes where Compassion serves. These are not the two character country codes used in the child’s identifying key. Optional String BD, BF, BO, BR, CO, DO, EC, ET, GH, GT, HN, HT, ID, IN, KE, LK, MX, NI, PE, PH, RW, SV, TG, TH, TZ, UG
Region Querystring Parameter. A single region where Compassion serves (see Notes for list). Optional String One of:
Africa
Asia
Central America and Caribbean
South America
AgeMinimum Querystring Parameter. Minimum age for children. Optional Numeric 1-22
AgeMaximum Querystring Parameter. Maximum age for children. Optional Numeric 1-22
BirthYear Querystring Parameter. Year of birth to filter. Optional Numeric
BirthMonth Querystring Parameter. Month of birth to filter. Optional Numeric 1-12
Birthday Querystring Parameter. Day of birth to filter. Optional Numeric 1-31
HivAffectedArea Querystring Parameter. True/false to include/exclude children that are affected by HIV. Optional Boolean Default: includes both
Orphan Querystring Parameter. True/false to include/exclude children that are orphans. Optional Boolean Default: includes both
SpecialNeeds Querystring Parameter. True/false to include/exclude children that have special needs. Optional Boolean Default: includes both
DaysWaitingMinimum Querystring Parameter. Number indicating the minimum number of days the child has been waiting for a sponsor Optional Numeric Example: 365 would return children that have been waiting at least a year.
CenterName Querystring Parameter. Part or all of a child development center’s name. Optional String Case-insensitive
CenterIdList Querystring Parameter. Comma-delimited list of child development center IDs. Optional String Format: [a-zA-Z]{2}\d{3}
Take Querystring Parameter. Determines the number of children to return. Optional Numeric

Default: 20
Maximum: 100

Skip Querystring Parameter. Children Search results include the total number of matches. Using the take and the total, skip can be used to paginate through the results. Optional Numeric If the skip is greater than the total number of children returned, no children are returned (but the total is still supplied).
Sort Querystring Parameter. Value indicating how the results should be sorted. LongestWaiting will return the children that have been waiting the longest first. Random will return random children matching the criteria. Optional String

Default: youngest

One of: youngest, oldest, longestwaiting, random

CampaignPoolId Querystring Parameter. Some children in the compassion.com pool are reserved for specific development activities (concerts, radio programs, etc). These children are not returned through typical searches. Passing a campaign ID will return only the children within that subset that match the other criteria supplied. Optional Numeric
SessionId Querystring Parameter. This is a client-specific identifier. The lock service uses this client session ID to restrict access to the children that are locked to that user. By supplying the session ID in searches, children that are locked to the user will still be included in the results (for only them). Optional GUID
api_key Querystring Parameter. Mashery-supplied key for accessing Compassion International services Yes String  

Specifying Format

By default, all requests will be returned as JSON. There are two ways to indicate an explicit format – either by using an extension on the endpoint (.json or .xml) or by setting the Accept header in the initial request (“application/json” or “application/xml”).

Sample Responses

JSON (/children/search.json?…)

{
    "totalMatches": 432,
    "children": [
        {
            "childKey": "BD2160220",
            "childName": "Jane Smith",
            "childPersonalName": "Jane",
            "countryName": "Bangladesh",
            "gender": "F",
            "age": 2,
            "birthDate": "2011-07-01T00:00:00",
            "waitingSinceDate": "2013-01-29T00:00:00",
            "orphan": false,
            "specialNeeds": false,
            "hivAffectedArea": false
        },
        {
            "childKey": "ME9630260",
            "childName": "John Doe",
            "childPersonalName": "John",
            "countryName": "Mexico",
            "gender": "M",
            "age": 2,
            "birthDate": "2011-07-11T00:00:00",
            "waitingSinceDate": "2012-10-31T00:00:00",
            "orphan": false,
            "specialNeeds": false,
            "hivAffectedArea": false
        },
        {
            "childKey": "ME8920367",
            "childName": "Sarah Johnson",
            "childPersonalName": "Sarah",
            "countryName": "Mexico",
            "gender": "F",
            "age": 2,
            "birthDate": "2011-02-24T00:00:00",
            "waitingSinceDate": "2013-05-08T00:00:00",
            "orphan": false,
            "specialNeeds": false,
            "hivAffectedArea": false
        },
        …
    ]
}

XML (/children/search.xml?…)

<ChildSearchResponse>
    <TotalMatches>432</TotalMatches>
    <Children>
        <Child>
            <ChildKey>ME9630260</ChildKey>
            <ChildName>John Doe</ChildName>
            <ChildPersonalName>John</ChildPersonalName>
            <CountryName>Mexico</CountryName>
            <Gender>M</Gender>
            <Age>2</Age>
            <BirthDate>2011-07-11T00:00:00</BirthDate>
            <WaitingSinceDate>2012-10-31T00:00:00</WaitingSinceDate>
            <Orphan>false</Orphan>
            <SpecialNeeds>false</SpecialNeeds>
            <HivAffectedArea>false</HivAffectedArea>
        </Child>
        <Child>
            <ChildKey>ME8920367</ChildKey>
            <ChildName>Jane Smith</ChildName>
            <ChildPersonalName>Jane</ChildPersonalName>
            <CountryName>Mexico</CountryName>
            <Gender>F</Gender>
            <Age>2</Age>
            <BirthDate>2011-02-24T00:00:00</BirthDate>
            <WaitingSinceDate>2013-05-08T00:00:00</WaitingSinceDate>
            <Orphan>false</Orphan>
            <SpecialNeeds>false</SpecialNeeds>
            <HivAffectedArea>false</HivAffectedArea>
        </Child>
        …
    </Children>
</ChildSearchResponse>

0 Comments

New comments are not being accepted at this time.

Docs Navigation