# Country API

Overview
API Location
Source File
- Headers
Processing
Sample Output

# Overview

This API provides information about STC's sponsorship countries to the sponsorship acquisition/retention portions of the site.

The data in this API are compiled from a client-provided XLS source file, processed by DNL into JSON format and uploaded to Luminate as a roll-your-own api.

# API Location

The API is located at /site/SPageNavigator/api/sponsorship/api_sponsor_countries.html?pgwrap=n (opens new window). Note that the pgwrap=n query string parameter is required as it prevents Luminate from including Page Wrapper code in the output of the request.

# Source File

The source data this API is rendered from was provided by STC. The latest version of the document can be found in DNL's Dropbox account (opens new window) and is available upon request.

# Headers

A list of the source file's headers, as well as expected values, are below.

Note: URLs for assets that are served from STC's CDN should use [[S80:staticAssetsBaseUrl]] for the domain-portion of the URL. This s-tag resolves to the proper CDN distribution for the Luminate environment.

# name

Name of country.

Ex. Bolivia, Egypt, Haiti

# description

Brief description that will display on acquisition profile pages.

Ex. When violence strikes in neighboring countries, refugees seek safety in urban Egyptian communities. But standards of living are low here, and children struggle to learn in overcrowded classrooms. Kids in rural areas face poor sanitation, high mortality rates and a miles-long trek to school.

Child sponsors like you provide critical support – from the cities of Greater Cairo to the agricultural villages of Abnoub. Save the Children helps families access medical check-ups and nutrition supplements and stocks local clinics with hygiene supplies and vaccines. Safe learning spaces and teacher training programs ensure children get a quality education no matter where they're from.

# heroTall

URL of hero image to use on sponsor child profile pages at large desktop screen resolutions.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/afghanistan-1700w.jpg

# heroLarge

URL of hero image to use on sponsor child profile pages at standard desktop screen resolutions.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/afghanistan-1170w.jpg

# heroMedium

URL of hero image to use on sponsor child profile pages at tablet desktop screen resolutions.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/afghanistan-750w.jpg

# heroSmall

URL of hero image to use on sponsor child profile pages at mobile desktop screen resolutions.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/afghanistan-640w.jpg

# heroAlt

Alt text to use for the hero image at every resolution.

Ex. Thanks to Save the Children sponsors, many classrooms and school buildings have been improved. Credit: Save the Children, 2016.

# factPopulation

Population fact for the country, used on sponsor child profile pages.

Ex. More than 32 Million people live here

# factEducation

Education fact for the country.

Ex. The average girl stays in school 10 years

# factDeath

Mortality fact for the country.

Ex. 97 out of 1,000 children die before their 5th birthday

# factIncome

Income fact for the country.

Ex. A parent earns an average of $2 a day

# mapImageUrl

URL of map graphic for the country.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/country-maps/afghanistan.jpg

# quoteText

Text of quote. Not in use as of this writing.

# quoteName

Attribution line for quote. Not in use as of this writing.

# quoteValign

How the quote text should be vertically aligned against its background image.

Ex. top, bottom

# quoteTall

URL of hero image to use behind quote area.

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/bangladesh-quote-1700w.jpg

# quoteLarge

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/bangladesh-quote-1170w.jpg

# quoteMedium

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/bangladesh-quote-750w.jpg

# quoteSmall

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/bangladesh-quote-640x600.jpg

# quoteAlt

Alt text for hero background image.

Ex. Safe motherhood and newborn care programs supported by sponsorship in Bangladesh set children up for a lifetime of success. Photo credit: Shafiqul Alam Kiron, 2011

# directorVideoUrl

URL of Youtube Embedded video from director of program.

Ex. https://www.youtube.com/embed/rfxzPllxAIc

# directorLearnMoreUrl

URL of Learn More page from director of program.

Ex. https://[[S80:mainSiteDomain]]/content/dam/sponsorship/report/bangladesh-2016-child-sponsorship-results-report.pdf

# timezone

Timezone for the country. Zone must be supported by the exact version of Moment Timezone (opens new window) currently in use by site. Check ./package.json file for version info.

Ex. Asia/Manila

# programVideoUrl

URL of Youtube Embedded video for program.

Ex. https://www.youtube.com/embed/fwLMYVBmHcE

# makeAdditionalGiftUrl

URL of Make Additional Gift asset. Set to static hashtag ('#') as of this writing.

# refugeeEnabled

true if refugee program is enabled, false or blank if it's disabled

# refugeeHeroTall

URL of hero image to use on a refugee country

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/egypt-1700w.jpg

# refugeeHeroLarge

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/egypt-1170w.jpg

# refugeeHeroMedium

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/egypt-750w.jpg

# refugeeHeroSmall

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/banners/egypt-640w.jpg

# refugeeHeroAlt

Refugee banner image alt text

Ex. Egypt's Nile River delta is home to more than 39 million people. Credit: Save the Children, 2015

# refugeeMapTitle

Ex. A New Home for Refugees

# refugeeMapImageUrl

Ex: [[S80:staticAssetsBaseUrl]]/wrpr/images/sponsorship/country-maps/egypt-refugee.jpg

# refugeeDirectorVideoUrl

URL of Youtube Embedded video for program.

Ex. https://www.youtube.com/embed/fwLMYVBmHcE

# refugeeDirectorBlurb

Ex. Egypt has a long history of hosting refugees from the Middle East and Africa. Most refugees live in rented accommodations alongside vulnerable Egyptian communities. Unemployment and inflation are high, and many families struggle to afford their rent and other essentials.

Save the Children has been responding to the Syrian refugee crisis in Egypt since 2013, particularly within the 6th of October City. Thousands of Syrians have made their way to this city, but struggle to access basic services like education due to overcrowded classrooms, complexities with the registration process, and shortages of teachers and service providers.

# refugeeDirectorLearnMoreUrl

Ex. https://www.savethechildren.org/us/what-we-do/emergency-response/refugee-children-crisis

# refugeeFact1

Ex. Egypt is now home to an estimated 193,000 asylum seekers and refugees

# refugeeFactIconUrl1

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/icons/tent-red.svg

# refugeeFact2

# refugeeFactIconUrl2

# refugeeFact3

# refugeeFactIconUrl3

# refugeeFact4

# refugeeFactIconUrl4

# refugeeProgramVideoUrl

Ex. https://www.youtube.com/embed/ghsj6Qm03M4

# refugeeSeeOurResultsUrl

Ex. https://www.savethechildren.org/content/dam/usa/reports/sponsorship/our-results-egypt-refugee.pdf

# refugeeCtaBox3Text

Ex. Refugee Crisis Explained

# refugeeCtaBox3ImageUrl

Ex. [[S80:staticAssetsBaseUrl]]/wrpr/images/member-center/sponsorship-refugee-crisis.jpg

# refugeeCtaBox3ImageAlt

Ex. This two-year-old refugee is struggling to keep warm in sub-zero temps in Greece. Her family's temporary shelter is a concrete warehouse. Photco credit: Anna Pantelia/Save the Children 2017.

# refugeeCtaBox3Url

Ex. https://www.savethechildren.org/us/what-we-do/emergency-response/refugee-children-crisis

# Processing

The process for converting the source data xlsx file into the usable API are as follows.

Use Microsoft Excel to convert the file to CSV format.
Convert the resulting CSV file to JSON with the STC Sponsorship Country Data API Generator (opens new window) tool. Usage instructions can be found in the readme.md of that project.
Put the output of that process to the API's PageBuilder Page, /site/SPageNavigator/api/sponsorship/api_sponsor_countries.html?pgwrap=n (opens new window).
Validate the output of the API to ensure it is properly formatted JSON. Malformed data in this api will break the sponsorship app. The easiest way to validate the data is the navigate to the API in a browser, copy the output and paste it into an online JSON validation tool (ex. JSONLint (opens new window)).

# Sample Output

{
      "director": {
          "videoUrl": "...",
          "blurb": "...",
          "learnMoreUrl": "..."
      },
      "facts": [
          {
              "type": "population",
              "message": "..."
          },
          {
              "type": "education",
              "message": "..."
          },
          {
              "type": "death",
              "message": "..."
          },
          {
              "type": "income",
              "message": "."
          }
      ],
      "heroes": {
          "largestImageUrl": "...",
          "largeImageUrl": "...",
          "mediumImageUrl": "...",
          "smallImageUrl": "..."
      },
      "makeAdditionalGiftUrl": "#",
      "mapImageUrl": "...",
      "name": "...",
      "description": "...",
      "programVideoUrl": "...",
      "timezone": "...",
      "quotes": {
          "heroes": {
              "largestImageUrl": "...",
              "largeImageUrl": "...",
              "mediumImageUrl": "...",
              "smallImageUrl": "..."
          },
          "text": "",
          "name": "",
          "valign": "..."
      },
      "heroAlt": "...",
      "quoteAlt": "..."
  },

  ...
]

← Child images Country filters →