Zomia Node.js API

Usage Notes

Zomia's REST API enables access to various Zomia SPC platform services.

Most services are accessible only to authorized users, although API calls resulting in public content have been exposed via https://api.zom.io/v1/Images/{Path} URLs. Examples are visible below.

Image Processing & Face Detection

The API enables image manipulation via options passed on the URL. Here's a pair of original, unprocessed images:

The following options may be passed in the URL after https://api.zom.io/v1/Images/S3/ as comma-delimited pairs (e.g., w_400,d_loose):

  1. w: {option: 'width', type: 'int', min: 10, max: 4000}
  2. h: {option: 'height', type: 'int', min: 10, max: 4000}
  3. f: {option: 'fit', type: 'string', accept: 'cover|contain|fill|inside|outside'} // For resizing, see https://sharp.pixelplumbing.com/api-resize
  4. g: {option: 'gravity', type: 'string'} // For cropping, see https://sharp.pixelplumbing.com/api-resize/#crop
  5. q: {option: 'quality', type: 'int', min: 1, max: 100} // JPEG/PNG/TIFF compression
  6. r: {option: 'rotate', type: 'int', min: 90, max: 270, accept: '90|180|270'}
  7. d: {option: 'faceDetection', type: 'string', accept:'tight|loose'} // Do we do any face detection on crop?
  8. e: {option: 'effects', type: 'array', accept: 'greyscale|flip|flop|contrasty'}
  9. b: {option: 'badge', type: 'string', accept: 'a|cap|trophy|dollar|pay|cap|star|star_multi'}
  10. c: {option: 'ribbonColor', type: 'string', accept: 'pink|blue|grayscale|round'}
  11. l: {option: 'badgeLocation', type: 'string', accept: 'right|left'}
  12. o: {option: 'apiOperation', type: 'string', accept: "process|round|square|portrait|portrait_round"}

Examples of face detection and other manipulation performed on the unprocessed/uncropped images above (no CSS applied):

Image Generator: E-mail Message Banners

The API enables generation of images for usage in Zomia's custom e-mail message/e-card template. Examples:

To customize e-mail banners, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/EmailBanner/{PATH} URL, where {PATH} consists of name/value pairs:

  1. Title - enter as name/value pair on the URL, e.g., "/Title/Grade%20Report/"
  2. Subtitle - enter as name/value pair, e.g., "/Subtitle/January%202018/"
  3. TextAlign (title/subtitle alignment) - enter as name/value pair where value is one of "left|center|right" (defaults center), e.g., "/TextAlign/right/"
  4. Color - enter a valid hexadecimal color value (defaults to Zomia blue), e.g., "/Color/333333/"
  5. *BaseUrl - This value MUST BE PRESENT AS THE LAST URL PARAMETER (last because the URL value will have any number of "/" characters present); this is the path to the base banner photo, e.g., /BaseUrl/https://cdn.zomia.org/images/banners/individuals/2017-09-23_5-000684_1728x864.jpg"

Image Generator: Loan MAP Schedules

Zomia's MAP schedules can also be generated dynamically via the API. Seen below are examples for both versions of Zomia's MAP:

To customize MAP schedules, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/MapSchedule/{PATH} URL, where {PATH} consists of name/value pairs:

  1. *LoanAmount - valid values range from 500 to 30,000, e.g., "/LoanAmount/13000/"
  2. *IndividualId - enter any student IndividualId to generate a MAP for that student, e.g., "/IndividualId/300001/" – note that the MAP version will be determined automatically based upon the student's loan contract
  3. MapVersion - enter 1 (pre-2018 MAP model) or 2 (2018 model) or 3 (2019 model), e.g., "/MapVersion/1/"; if no MapVersion is entered, the current model (version 3, 2019) is used

* Either LoanAmount or IndividualId must be specified, but not both at once.

Image Generator: Student Pie Charts

Produce pie charts based upon student data - must pass IndividualId, LoanId, or Percentage (0-100) and Mode, e.g., /Images/Generator/Pie/IndividualId/300001/Mode/Repaid

To customize pies, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/Pie/{PATH} URL, where {PATH} consists of name/value pairs:

  1. *Mode - one of Funded or Repaid, if anything else (e.g., "Filled"), a Percentage option must be specified
  2. Percentage - 0 to 100, manually set percentage displayed in pie chart - required if Mode is not Funded or Repaid
  3. Color - six-digit HEX, no #
  4. Background - six-digit HEX, no #, background-color upon which pie is rendered
  5. OmitText - 1/true to skip generation of the percentage text overlay
  6. TextPercentageOnly - 1/true to display only the percentage as the text overlay
  7. Width - number, in pixels
  8. Height - number, in pixels
  9. Donut - 1|0, set to 1 to render a donut
  10. DonutColor - six-digit HEX, no #
  11. TextColor - six-digit HEX, no #
  12. Format - jpg|png|JPG|PNG
  13. Quality - 1 to 100, with 100 being best, generally only affects JPG output

Image Generator: Student Pie Portraits

Produce pie charts layered atop student portraits - must pass IndividualId, LoanId, or Percentage (0-100) and Mode, e.g., /Images/Generator/PiePortrait/IndividualId/300001/Mode/Repaid. Same options apply as Pie module above.

Image Generator: Individual/Organization Portraits & Thumbnails

Generate platform entity portraits and thumbnails. Follows similar pattern used with PiePortrait above, although EntityId, OrganizationId, or IndividualId may be passed to designate the entity. Examples:

To customize portraits and thumbnails, the following elements may be added to the base https://api.zom.io/v1/Images/Generator/EntityId/XXXXXX/Portrait/{PATH} or .../Thumbnail/{PATH} URL, where {PATH} consists of name/value pairs:

  1. Width - number, in pixels
  2. Height - number, in pixels
  3. Sharpen - number between 1 and 10 for sharpening level (useful for tiny thumbnail generation)