z.eer.io API

z.eer.io provides a simple API with a couple features that make posting rich media to App.net much easier.

Authentication

To keep the entire internet from consuming z.eer.io's server resources, these APIs are limited to App.net users through App.net's Identity Delegation. Essentially this means if an App.net user had authorized your app, you can "prove" that to z.eer.io in order to get access to the API. Read the App.net docs (above) for details.

If you're using AppDotNetPHP for your app, fetching a delegate token would look something like this:

$app = new AppDotNet(CLIENT_ID,CLIENT_SECRET);
$app->setAccessToken(USER_TOKEN);
$delegateToken = $app->getDelegateToken(CLIENT_ID);

If you're using another framework or rolling your own, fetching a delegate token it should be similarly easy.

Once you have the token, you'll pass it to z.eer.io's API with either the IDENTITY_DELEGATE_TOKEN HTTP header, or as a GET or POST parameter named delegate_token. You'll also need to include either the IDENTITY_DELEGATE_ENDPOINT HTTP header, or the GET or POST delegate_endpoint parameter, which (for app.net) is always set to https://api.app.net/token.

Fetch Meta Data (including oEmbed) for a URL

This allows you to pass a single URL and get back some useful data about it. Mostly useful for "share" type apps where you want to "share" (post) a link to App.net.

Endpoint

https://z.eer.io/api/fetch

Request Parameters

delegate_endpoint (or the IDENTITY_DELEGATE_ENDPOINT HTTP header)

(Required) "https://api.app.net/token"

delegate_token (or the IDENTITY_DELEGATE_TOKEN HTTP header)

(Required) The end user's app.net delegate token

url

(Required) The URL to fetch meta information for

Response

A JSON object containing the following properties:

title

The title of the page found at the specified URL. Most commonly this is found in the <title> tag on the page. If no title was found, this will be null.

description

The description of the page found at the specified URL. This can come from the <meta> description tag, or from other similar tags (like twitter or facebook meta tags). If no description was found, this will be null.

icon

If the page specifies a "favicon" this is the URL to that icon. If no favicon was found, this will be null.

oembeds

An oembed object representing the content on the page, ordered from "most important" to "least important". If you only want to include a single piece of embedded media, and don't want to build a UI for the user to select one, you can generally use the first item. If no embeddable media was found on the page, this will be an empty array.

Example

https://z.eer.io/api/fetch?delegate_endpoint=https://api.app.net/token&delegate_token=[[token]]&url=https://www.youtube.com/watch?v=GeyDf4ooPdo

{
	"title":"Anti-Gravity Wheel? - YouTube",
	"description":"Explanation of gyro precession: http:\/\/bit.ly\/U4e8HQ More: http:\/\/bit.ly\/GyroMORE Less Than: http:\/\/bit.ly\/GyroLESS Equal To: http:\/\/bit.ly\/GyroEQUAL Huge th...",
	"icon":"https:\/\/s.ytimg.com\/yts\/img\/favicon_32-vflWoMFGx.png",
	"oembeds":[{
		"author_name":"Veritasium",
		"title":"Anti-Gravity Wheel?",
		"thumbnail_width":"480",
		"author_url":"http:\/\/www.youtube.com\/user\/1veritasium",
		"width":"640",
		"thumbnail_url":"http:\/\/i.ytimg.com\/vi\/GeyDf4ooPdo\/hqdefault.jpg",
		"height":"360",
		"provider_url":"http:\/\/www.youtube.com\/",
		"thumbnail_height":"360",
		"type":"video",
		"version":"1.0",
		"provider_name":"YouTube",
		"html":"<iframe width=\"640\" height=\"360\" src=\"http:\/\/www.youtube.com\/embed\/GeyDf4ooPdo?feature=oembed\" frameborder=\"0\" allowfullscreen><\/iframe>",
		"embeddable_url":"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo"
	}]
}

Extract Links and Meta Data From a Text String

This takes advantage of the fact that z.eer.io can understand links specified in HTML, Markdown, BBCode and just plain URLs, parses them out for you, fetches meta data for each of them, and returns the results. This is useful if you're allowing users to add text that might include links (like a general posting app) and you want to embed the media from those links. As a general rule it'll be faster to parse the links locally, and if some are found use the "fetch" method above for each link, however this is far simpler and can be updated live (without updating your app).

Endpoint

https://z.eer.io/api/parse

Request Parameters

delegate_endpoint (or the IDENTITY_DELEGATE_ENDPOINT HTTP header)

(Required) "https://api.app.net/token"

delegate_token (or the IDENTITY_DELEGATE_TOKEN HTTP header)

(Required) The end user's app.net delegate token

text

(Required) The URL to fetch meta information for

options

A JSON encoded object containing one or more of the following options.

parse

An array of one or more formats you want to parse from the provided text, default is all. Valid formats are: "html", "markdown", "bbcode", and "urls" (finds raw URLs in the text and turns them into links).

generate

An array of one or more formats you want to return, after parsing the text. Default is none. Valid formats are: "html", "markdown", "bbcode", and "app.net". For every generate format you include, the response JSON object will contain that property where the value is the formatted item.

Response

A JSON object containing the following properties:

text

The resulting text after all formatting has been removed.

html

If the generate array in the request options contained "html", this property will be an HTML formatted version of the text with links.

markdown

If the generate array in the request options contained "markdown", this property will be an Markdown formatted version of the text with links.

bbcode

If the generate array in the request options contained "bbcode", this property will be an BBCode formatted version of the text with links.

app.net

If the generate array in the request options contained "app.net", this property will be an object formatted as an App.net post object. You should be able to take this object and pass it to the App.net API unaltered, although you can of course customize it before you do.

links

An array of objects, each representing one link found in the provided text. If no links were found in the text, then this property will be an empty array. Each object contains:

pos

The start position (character position, zero based) in text. Be sure that your counting CHARACTERS and not BYTES, as all z.eer.io uses UTF-8 for all strings.

len

The length of the link in characters, starting from pos. Be sure that your counting CHARACTERS and not BYTES, as all z.eer.io uses UTF-8 for all strings.

text

The text or title of the link (what should be displayed to users).

url

The URL of the link.

linksMeta

An array of objects, corresponding to the "links" array above (eg: element 0 of the links array and element 0 of the linksMeta array refer to the same URL), each containing all the meta data you would get back if you had done a "fetch" request (see above).

Example

Text is: <a href="https://www.youtube.com/watch?v=GeyDf4ooPdo">A YouTube Video</a>

Options is: {"parse":{"html":true,"markdown":true,"bbcode":true,"urls":true},"generate":{"html":true}}

https://z.eer.io/api/parse?delegate_endpoint=https://api.app.net/token&delegate_token=[[token]]&text=%3Ca+href=%22https://www.youtube.com/watch?v=GeyDf4ooPdo%22%3EA+YouTube+Video%3C/a%3E&options=%7B%22parse%22%3A%7B%22html%22%3Atrue%2C%22markdown%22%3Atrue%2C%22bbcode%22%3Atrue%2C%22urls%22%3Atrue%7D%2C%22generate%22%3A%7B%22html%22%3Atrue%7D%7D

{
	"text":"A YouTube Video",
	"html":"<a href=\"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo\">A YouTube Video<\/a>",
	"markdown":"[A YouTube Video](https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo)",
	"bbcode":"[url=https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo]A YouTube Video[\/url]",
	"app.net":{
		"text":"A YouTube Video",
		"entities":{
			"links":[{
				"len":15,
				"pos":0,
				"text":"A YouTube Video",
				"url":"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo"
			}]
		},
		"annotations":[{
			"type":"net.app.core.oembed",
			"value":{
				"author_name":"Veritasium",
				"title":"Anti-Gravity Wheel?",
				"thumbnail_width":"480",
				"author_url":"http:\/\/www.youtube.com\/user\/1veritasium",
				"width":"640",
				"thumbnail_url":"http:\/\/i.ytimg.com\/vi\/GeyDf4ooPdo\/hqdefault.jpg",
				"height":"360",
				"provider_url":"http:\/\/www.youtube.com\/",
				"thumbnail_height":"360",
				"type":"video",
				"version":"1.0",
				"provider_name":"YouTube",
				"html":"<iframe width=\"640\" height=\"360\" src=\"http:\/\/www.youtube.com\/embed\/GeyDf4ooPdo?feature=oembed\" frameborder=\"0\" allowfullscreen><\/iframe>",
				"embeddable_url":"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo"
			}
		}]
	},
	"links":[{
		"len":15,
		"pos":0,
		"text":"A YouTube Video",
		"url":"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo"
	}],
	"linksMeta":[{
		"title":"Anti-Gravity Wheel? - YouTube",
		"description":"Explanation of gyro precession: http:\/\/bit.ly\/U4e8HQ More: http:\/\/bit.ly\/GyroMORE Less Than: http:\/\/bit.ly\/GyroLESS Equal To: http:\/\/bit.ly\/GyroEQUAL Huge th...",
		"icon":"https:\/\/s.ytimg.com\/yts\/img\/favicon_32-vflWoMFGx.png",
		"oembeds":[{
			"author_name":"Veritasium",
			"title":"Anti-Gravity Wheel?",
			"thumbnail_width":"480",
			"author_url":"http:\/\/www.youtube.com\/user\/1veritasium",
			"width":"640",
			"thumbnail_url":"http:\/\/i.ytimg.com\/vi\/GeyDf4ooPdo\/hqdefault.jpg",
			"height":"360",
			"provider_url":"http:\/\/www.youtube.com\/",
			"thumbnail_height":"360",
			"type":"video",
			"version":"1.0",
			"provider_name":"YouTube",
			"html":"<iframe width=\"640\" height=\"360\" src=\"http:\/\/www.youtube.com\/embed\/GeyDf4ooPdo?feature=oembed\" frameborder=\"0\" allowfullscreen><\/iframe>",
			"embeddable_url":"https:\/\/www.youtube.com\/watch?v=GeyDf4ooPdo"
		}]
	}]
}