Fetching Data

oEmbed

oEmbed is a simple standard that makes it easy to embed a small alternate version of a web page in various other contexts. At Kiva, we currently support oEmbed for our borrower profile pages.

What's it for?

The first site to take advantage of our oEmbed support was Twitter. You can read about what they were able to do with it in their blog post.

How it works

oEmbed requests occur between two parties: a consumer makes the request, and a provider returns a response. To construct an oEmbed request, the consumer has to know a scheme and an endpoint. Using the scheme and endoint, the consumer can construct a URL like this:

http://www.kiva.org/services/oembed?url=http%3A//www.kiva.org/lend/100000
The provider then returns a response, generally in XML or JSON, conforming the oEmbed spec. In this case, the consumer would get back a response including:
"version":"1.0", "type":"rich", "title":"Kiva - Bibi Najeba Group's Loan", "width":450, "height":300, "html":" <-- xhtml fragment to be embedded, omitted here for brevity --> "

The consumer can use this data to render a version of a resource as an embedded widget. To learn more about how oEmbed works, check out the oEmbed spec.

Kiva scheme and endpoint:

We currently support oEmbed for one URL scheme, which is our borrower profile page.

Scheme
http://www.kiva.org/lend/*
Endpoint
http://www.kiva.org/services/oembed

Optional parameters

All requests to the endpoint must include a "url" parameter conforming to a supported scheme. In addition, the following optional parameters are supported

format
One of ("json" | "xml" | "jsonp"* | "preview"**) The default is "xml"
maxwidth
See the oEmbed spec. Usually unnecessary
maxheight
See the oEmbed spec. Usually unnecessary
jsonp *
Required if format is "jsonp". This is the name of the jsonp callback to use.

* nonstandard. Jsonp support makes it easier to use oEmbed in a client-side application, but is not entirely without risk for the consumer.

** nonstandard. Returns the html fragment only, as an aid during development.

Discovery

Our oEmbed support is discoverable. The <head> of the borrower profile page includes two <link> tags that point to the corresponding xml and json oEmbed URLs, like this:
<link rel="alternate" type="application/json+oembed" href="http://www.kiva.org/services/oembed?url=http%3A%2F%2Fwww.kiva.org%2Flend%2F100000&format=json" title="Bibi Najeba Group's Loan from Afghanistan (JSON oEmbed view)" /> <link rel="alternate" type="text/xml+oembed" href="http://www.kiva.org/services/oembed?url=http%3A%2F%2Fwww.kiva.org%2Flend%2F100000&format=xml" title="Bibi Najeba Group's Loan from Afghanistan (XML oEmbed view)" />
Kiva
  • © 2009 - 2014 Kiva. All rights reserved.
  • Terms Of Service
  • Kiva is a 501(c)(3) nonprofit.