REST Get Country V1

The Country Information API is a RESTful API. The service provides various types of information on a country.

One of the following parameters is required:

  • Country Id
  • ISO Country Code
  • Legacy Country Code

The service returns JSON as default. The service will also return XML. This is controlled by the Accept parameter in the Message Header (i.e., for XML, it should be "Accept: application/xml" and for JSON, it should be "Accept: application/json").

Sample Requests
Request Parameters
Response Parameters
XML Sample Successful Response
JSON Sample Successful Response
Sample Unsuccessful Responses
Error Response Codes

Sample Requests

The actual request requires soft-authentication.
This is an example only.

IPTE URLs
https://api2.compassion.com/iptest/ci/v1/countries/{id}?ClientReferenceId=[string]&api_key=[string]
https://api2.compassion.com/iptest/ci/v1/countries/iso/{iso-country-code}?ClientReferenceId=[string]&api_key=[string]
https://api2.compassion.com/iptest/ci/v1/countries/legacy/{compassion-countrycode}?ClientReferenceId=[string]&api_key=[string]
Production URLs
https://api2.compassion.com/ci/v1/countries/{id}?ClientReferenceId=[string]&api_key=[string]
https://api2.compassion.com/ci/v1/countries/iso/{iso-country-code}?ClientReferenceId=[string]&api_key=[string]
https://api2.compassion.com/ci/v1/countries/legacy/{compassion-countrycode}?ClientReferenceId=[string]&api_key=[string]

Request Parameters

Name Description Required Data Type Constraints
Id Three-digit code assigned to a country by the International Organization for Standardization (ISO). This is an integer and can have a leading zero. Conditional Numeric Max 3
ISO-Country-Code Two-character code assigned to a country by the International Organization for Standardization (ISO) as defined in the ISO 3166-1 standard. Conditional String Max 2
Compassion-CountryCode Two-character legacy country code that is used to identify field offices within Compassion International. Conditional String Max 2
ClientReferenceId Uniquely represents the transaction in the client's system. Optional String Max 100
api_key Your Mashery supplied key for an application running Compassion International services. Yes String  

Response Parameters

Name Description Data Type Returned
CountryId Code assigned to a country by the International Organization for Standardization (ISO). number
ISOCountryName Name for a country as recorded by the International Organization for Standardization (ISO) in the ISO 3166-1 standard. string
ISOCountryCode Two-character code assigned to a country by the International Organization for Standardization (ISO) as defined in the ISO 3166-1 standard. string
CountryCommonName Common name of a country as used by Compassion International. string
CountryDescription Description of the country. string
CountryInternationalPhoneCode Telephone code for international dialing. string
CountryPopulation Population of the country. string
GovernmentType Government type of the country. string
OfficialReligion Predominate religion of the country. string
OfficialLanguage Official language of the country. string
OfficialCurrency Official currency of the country. string
LifeExpectancy Life expectancy of person in the country. string
PerCapitaIncomeinUSDollars Per capita income of individuals in the country. string
InfantMortalityRate Number of infants that die per 1000 born. Formula to obtain a percentage: (InfantMortalityRate/1000)*100 string
Under5MortalityRate Number of children under five years of age that die per 1000 that are born. Formula to obtain a percentage: (InfantMortalityRate/1000)*100 string
PercentOfChildrenThatReachUS5thGradeEquivalent Percent of children that reach US equivalent of a fifth grade education. string
AverageYearstoCompletePrimarySchool Average years it takes a child to complete primary education. string
ExpectedYearstoCompletePrimarySchool Expected number of years it takes a child to complete primary education. string
PercentofPopulationHindu Percentage of population that is Hindu. string
PercentofPopulationAnimist Percent of population that is Animist. string
PercentofPopulationBuddhist Percentage of population that is Buddhist. string
PercentofPopulationCatholic Percent of population that is Catholic. string
PercentofPopulationProtestant Percentage of population that is Protestant. string
PercentofPopulationMuslim Percent of population that is Muslim. string

XML Sample Success Response

<Country  xmlns="http://schemas.ci.org/ci/common/eim/2014/10/">
  <CountryID>[number]</CountryID>
  <ISOCountryName>Bolivia, Plurinational State Of</ISOCountryName>
  <ISOCountryCode>BO</ISOCountryCode>
  <CountryCommonName>Bolivia</CountryCommonName>
  <CountryDescription>[text]</CountryDescription>
  <CountryInternationalPhoneCode>59</CountryInternationalPhoneCode>
  <CountryPopulation>7593</CountryPopulation>
  <GovernmentType>Republic</GovernmentType>
  <OfficialReligion>Catholic</OfficialReligion>
  <OfficialLanguage>Spanish Quechua Aymara</OfficialLanguage>
  <OfficialCurrency>BO Boliviano</OfficialCurrency>
  <LifeExpectancy>59.00</LifeExpectancy>
  <PerCapitaIncomeInUSDollars>2530.0000</PerCapitaIncomeInUSDollars>
  <InfantMortalityRate>71</InfantMortalityRate>
  <Under5MortalityRate>102</Under5MortalityRate>
  <PercentOfChildrenThatReachUS5thGradeEquivalent>60.40</PercentOfChildrenThatReachUS5thGradeEquivalent>
  <AverageYearsToCompletePrimarySchool>13</AverageYearsToCompletePrimarySchool>
  <ExpectedYearsToCompletePrimarySchool>8</ExpectedYearsToCompletePrimarySchool>
  <PercentOfPopulationHindu>0.00</PercentOfPopulationHindu>
  <PercentOfPopulationAnimist>0.00</PercentOfPopulationAnimist>
  <PercentOfPopulationBuddhist>0.00</PercentOfPopulationBuddhist>
  <PercentOfPopulationCatholic>95.00</PercentOfPopulationCatholic>
  <PercentOfPopulationProtestant>0.00</PercentOfPopulationProtestant>
  <PercentOfPopulationMuslim>0.00</PercentOfPopulationMuslim
</Country>

JSON Sample Successful Response

{
  "countryID":[number],
  "isoCountryName":"Bolivia, Plurinational State Of",
  "isoCountryCode":"BO",
  "countryCommonName":"Bolivia",
  "countryDescription":"[text]",
  "countryInternationalPhoneCode":"59",
  "countryPopulation":"7593",
  "governmentType":"Republic",
  "officialReligion":"Catholic",
  "officialLanguage":"Spanish Quechua Aymara",
  "officialCurrency":"BO Boliviano",
  "lifeExpectancy":"59.00",
  "perCapitaIncomeInUSDollars":"2530.0000",
  "infantMortalityRate":"71",
  "under5MortalityRate":"102",
  "percentOfChildrenThatReachUS5thGradeEquivalent":"60.40",
  "averageYearsToCompletePrimarySchool":"13",
  "expectedYearsToCompletePrimarySchool":"8",
  "percentOfPopulationHindu":"0.00",
  "percentOfPopulationAnimist":"0.00",
  "percentOfPopulationBuddhist":"0.00",
  "percentOfPopulationCatholic":"95.00",
  "percentOfPopulationProtestant":"0.00",
  "percentOfPopulationMuslim":"0.00"
}

Sample Unsuccessful Responses

XML Unsuccessful Response
<Error
  <ID>[string]</ID
  <Message>Incorrect data type: ID can only be numeric digits (0-9).</Message>
</Error>


 

JSON Unsuccessful Response
{
  "error": {
    "id": "[string]"
    "message""Incorrect data type: ID can only be numeric digits (0-9)."
  }
}

Error Response Codes

The table below indicates the HTTP error response and HTTP Error message.

HTTP Error Response HTTP Error Message
HTTP 400 Service Parameter Failure
HTTP 401 Not Authenticated / Authorized for Service Data
HTTP 403 Not Authorized
HTTP 403 Account Inactive
HTTP 403 Over Queries Per Second Limit
HTTP 403 Over Rate Limit
HTTP 403 Unknown Referrer
HTTP 404 Requested Resource Not Found
HTTP 408 Request Timeout
HTTP 414 Request URI Too Long
HTTP 500 Internal Server Error
HTTP 502 Bad Gateway
HTTP 503 API Maintenance / Service Unavailable
HTTP 504 Gateway Timeout

Docs Navigation