Fetching Data

Media

Images and other media at Kiva are composed of an immense amount of data as compared with other types of data in the Kiva API. Since it's not reasonable to embed this data our API responses, and since most people want to embed images in applications and web pages anyway, we have a simple template system for referencing images.

Images

An image in the Kiva API is represented by an id and a template_id. For example, here's a sample image reference for a borrower picture:

"image": { "id": 181707, "template_id":1 }

The specific template you can use for an image can depend on the photo. This photo uses the image template with ID 1 which looks like this:

http://www.kiva.org/img/<size>/<id>.jpg

The ID part of the template makes sense, but what about the size? For any image at Kiva, you can choose any value for the size. These are the options:

  • Specify height: http://www.kiva.org/img/h300/691404.jpg the width will be automatically chosen based on the aspect ratio of the original image.
  • Specify width: http://www.kiva.org/img/w300/691404.jpg the height will be automatically chosen based on aspect ratio.
  • Specify both: http://www.kiva.org/img/h300w300/691404.jpg the image will be resized to fit inside that space, which means that for images that aren't 1:1 width/height ratios, one of the dimensions will be less than what you requested.
  • Squared http://www.kiva.org/img/s300/691404.jpg the image will be returned as a square.
  • Full Size http://www.kiva.org/img/fullsize/691404.jpg Get the full size image.

When you request an image that is not one of the standard sizes used on Kiva's site, the request will cause that image to be generated and cached.

If you use one of our standard sizes, the image will already be pre-cached on our server and returned faster. Our standard sizes are:

  • w80h80
  • w200h200
  • w325h250
  • w450h360
  • s300
  • fullsize

For each of the values that specify both height and width, you will get an image whose maximum dimension is scaled to the value supplied. For an image that is 800 pixels wide and 600 pixels high, using w80h80 will provide an image sized to 80 pixels wide and 60 pixels high. fullsizereturns the largest version of the image available. For the "s<dimension>" (ex: "s300") pattern, you will get a squared image (in this example: 300px x 300px). Squared images are handy for various layout types, such as Kiva's home page. A word of caution: squared images can sometimes crop people out of the photo; for wide photos, the cropping routine cuts off the left and right sides evenly. This can sometimes crop individuals out if they are on the sides which is especially common in group photos. If the image is tall, the cropping routine cuts the bottom of the photo off since most images of borrowers have their heads in the top part of the photos. Squared images are good for certain layout types, but when showing a "zoomed in" version, it's best to use the other sizing options to prevent cropping people out.

Knowing the template pattern, we can put the values together and create an image URL from our template:

http://www.kiva.org/img/w200h200/181707.jpg

Image URL Templates

In the example above we showed you the image template with ID 1. From where do templates come? As it turns out, we have an API method for that too. Since we expect the number of image templates we use to be small, we have one simple method that returns them all of them to you at once:
http://api.kivaws.org/v1/templates/images.json

A good practice would be to cache the output from this call in your application and only refresh it when you see a template ID that isn't in your cached version. (We promise we'll never change the value of a template for given ID.) You could take things a step further and include a cached version as a part of your application's data resources. Since we currently only use one template ID for all the images at Kiva, it's possible that your app would never refresh the template list for images! However, a robust application would be prepared for the introduction of a new template at any time.

Since there is only one image template ID (1) in the Kiva API you might cache this in your application, but be prepared to fetch an updated template list if you see a new one in the future.

Video

Kiva supports video only in loan profiles and journal entries at the moment. You won't find a video for every loan or journal entry, but when you do it will look like this:

"video": { "id": 383, "youtube_id":"Yu_moia-oVI" }

Videos don't have templates. Instead we refer you to the YouTube API for information on how to embed, present, or otherwise handle video in your application. Currently all video at Kiva is hosted by YouTube.

A thumbnail image for every video is available. Currently the thumbnail image is the same as the primary image for the loan or journal entry.

Kiva
  • © 2009 - 2013 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.