Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Branch: master
Fetching contributors…

Cannot retrieve contributors at this time

425 lines (362 sloc) 17.344 kB


Annotations are metadata that are attached to Post when they are created. This allows developers and users to add extra information to the post without interfering with the text content of the Post. Annotations will enable developers to build complex posts and new systems on top of the current infrastructure.

We're really excited to be launching this feature and appreciate any feedback on the following document. Please open a github issue to contribute to this document.

Concretely, what are annotations

Let's say I'm at a restaurant eating a great dinner, but instead of just telling my followers about this restaurant I want them to be able to see a map of where it is. My Post could include geographic information about the address for the restaurant and then clients that support this geographic annotation could show the restaurant on a map (in addition to showing my post). If the restaurant is on OpenTable, I could include an annotation indicating that and my followers could see the menu and make a reservation in their own client. Annotations are what power complex posts with maps, pictures, videos, etc.

As a developer, why should I use annotations

To build amazing things. This feature enables new ideas to be built without having to create a brand new API or ecosystem to support the idea. This is the plumbing that will enable new kinds of clients that aren't just about microblogging.

Annotations are how will do reposting, geographic information, attaching media to posts, and lots of other things that our 3rd party developers will create.

How do I use annotations

As a non-developer

Right now, we're still working with developers to build out this system. As clients and apps are developed that support annotations, we'll be updating everyone on

As a developer

We're still working on updating all the sample Posts in the spec to show this annotations format.

First here are some of the more technical details of annotations:

  • Each annotation can be thought of as a dictionary or JSON object.
  • Each Post is allowed at most 8192 bytes worth of annotations (in total, when serialized as JSON).
  • Annotations are immutable and can only be added to a Post at creation time.

Annotation format

Here's a sample post with annotations:

    "annotations": [
            "type": "com.example.awesome",
            "value": {
                "annotations work": "beautifully"
    "created_at": "2012-08-30T23:30:14Z",
    "entities": {
        "hashtags": [],
        "links": [],
        "mentions": []
    "html": "<span itemscope=\"\">first annotation post</span>",
    "id": "1",
    "num_replies": 0,
    "num_reposts": 0,
    "num_stars": 0,
    "source": {
        "link": "",
        "name": ""
    "text": "first annotation post",
    "thread_id": "1255",
    "user": {...},
    "you_reposted": false,
    "you_starred": false

The post.annotations field will be a list of individual annotation objects.

Field Type Description
type string A string that looks like a reversed domain name to identify the data format for this annotation. There is no authentication or authorization performed on this field. Just because you create annotations with the type com.example.awesome does not imply you are the only one that is using that namespace or that the value will match the format you expect.
value object A complex object containing the metadata for this annotation. Be extremely careful with this data, except for well known annotations, no validation is performed on this field.

Creating annotations

Annotations are currently live on in the API. To create them you must give a well-formed JSON encoded post that matches the Post schema. Please see the Create Post documentations for more information.

Displaying annotations

Every client can choose if/how it chooses to display annotations. As stated above be very careful when consuming this data and do not assume that it follows a specific schema. Treat data in annotations as untrusted data. Program defensively: your app should not crash or otherwise throw an error if it receives a string where there is usually a dictionary, etc. will coordinate with the community to define schemas for common annotation formats. They will live under the* namespace. This is the only restricted annotation namespace. Any annotation in this namespace must be validated by the API against a published schema. Outside of this namespace, developers may create annotations in either the[username] namespace or a reversed-domain namespace of their choosing.

Since annotations can be up to 8192 bytes, they are not included with posts by default. When you make a request for posts, you can include the parameter include_annotations=1 to receive the annotations object. See general Post parameters for more information.

Annotations formats

Since annotations are just launching, we invite the community to propose schemas and collaborate on them. is currently working with the community to define common schemas for things like photos, other media, and geographic data. To propose these formats, please open an issue and tag it with the annotations label.

Some annotations are core to the platform and their schemas will be published below. Other schemas may be useful across multiple apps, but not be "core" to the platform. The community has started a page on the API wiki to catalog these common non-core annotations.

We will be defining core annotations soon for the following types of data:

  • Media enclosures, e.g., photos, video, etc.
  • Long-form content
  • Attribution and source
  • Additional content license grants, where users can opt in to Creative Commons licensing, etc., if desired.

Developers are invited to create ad-hoc annotations for data not well represented here; if possible, care should be taken not to overlap with existing annotations. If possible, Posts with ad-hoc annotations designed to address edge-cases in well-known annotations should include both the well-known annotation and only the augmented parts in the ad-hoc annotation.

Core Annotations


The crosspost annotation is meant to specify the original or canonical source of a Post on from somewhere else on the web.


    "type": "",
    "value": {
        "canonical_url": "",


Field Required? Type Description
canonical_url Required string A valid URL pointing to the source of the original content.

Embedded Media

The embedded media annotation specifies an image, video, or other rich content that should be displayed with this post. It uses the JSON oEmbed specification. We only support the photo, video, and rich oEmbed types.

We highly recommend providing the embeddable_url attribute so other clients can request different oEmbed details for this object from the original oEmbed provider (if there is one).


    "type": "",
    "value": {
        "version": "1.0",
        "type": "photo",
        "width": 240,
        "height": 160,
        "title": "ZB8T0193",
        "url": "",
        "author_name": "Bees",
        "author_url": "",
        "provider_name": "Flickr",
        "provider_url": "",
        "embeddable_url": ""
    "type": "",
    "value": {
        "version": "1.0",
        "type": "video",
        "provider_name": "YouTube",
        "provider_url": "",
        "width": 425,
        "height": 344,
        "title": "Amazing Nintendo Facts",
        "author_name": "ZackScott",
        "author_url": "",
            "<object width=\"425\" height=\"344\">
                <param name=\"movie\" value=\"\"></param>
                <param name=\"allowFullScreen\" value=\"true\"></param>
                <param name=\"allowscriptaccess\" value=\"always\"></param>
                <embed src=\"\"
                    type=\"application/x-shockwave-flash\" width=\"425\" height=\"344\"
                    allowscriptaccess=\"always\" allowfullscreen=\"true\"></embed>
        "embeddable_url": ""
    "type": "",
    "value": {
        "provider_url": "",
        "description": "Listen to Merenti - La Karambaa by M\u00e9renti | Create, record and share the sounds you create anywhere to friends, family and the world with SoundCloud, the world's largest community of sound creators.",
        "title": "Merenti - La Karambaa by M\u00e9renti",
        "html": "<iframe width=\"500\" height=\"166\" scrolling=\"no\" frameborder=\"no\" src=\"\"></iframe>",
        "author_name": "M\u00e9renti",
        "height": 166,
        "width": 500,
        "thumbnail_url": "",
        "thumbnail_width": 500,
        "version": "1.0",
        "provider_name": "SoundCloud",
        "type": "rich",
        "thumbnail_height": 500,
        "author_url": ""
        "embeddable_url": ""


To correspond with the oEmbed spec, this annotation accepts keys that are not specified below.

Field Required? Type Description
type Required string photo, video, or rich corresponding to the oEmbed type.
version Required string Must be 1.0.
width Required integer The width in pixels needed to display the embeddable content.
height Required integer The height in pixels needed to display the embeddable content.
url Required if type="photo" string The source URL for the image.
html Required if type="video" or type="rich" string The HTML to display the rich or video content. It should have no margins or padding. does no validation of of this field. Please program defensively. You may wish to load this in an off-domain iframe to avoid XSS vulnerabilities.
embeddable_url Optional (but recommended) string A URL that can be given to an oEmbed provider to recreate the oEmbed data contained in this annotation. This is useful so other clients can get updated information or retrieve a different sized embedding through an oEmbed endpoint.
title Optional string A title for this embedded content.
author_name Optional string The author of this embedded content.
author_url Optional string The URL for the author of this embedded content.
provider_name Optional string The service that provides this embedded content.
provider_url Optional string The URL for the service that provides this embedded content.
cache_age Optional integer How long (in seconds) should clients cache the embedded content.
thumbnail_url Optional string A URL to an image that represents this resource. If this parameter is specified, thumbnail_height and thumbnail_width must also be present.
thumbnail_height Optional string The height of the thumbnail image. If this parameter is specified, thumbnail_url and thumbnail_width must also be present.
thumbnail_width Optional string The height of the thumbnail image. If this parameter is specified, thumbnail_height and thumbnail_url must also be present.


The geolocation annotation is meant to specify a geographic point on the Earth. It is not meant to specify:

  • a human place (city, building, park, "San Francisco", "The Mission", "The Moscone Center"). We're investigating how to efficiently provide this data in the core api.
  • paths, regions, or complex geographic shapes. We recommend using a common schema (like GeoJSON) in your own annotation if you need this kind of solution.


Just the required parameters:

    "type": "",
    "value": {
        "latitude": 74.0064,
        "longitude": 40.7142,

With all optional parameters:

    "type": "",
    "value": {
        "latitude": 74.0064,
        "longitude": 40.7142,
        "altitude": 4400,
        "horizontal_accuracy": 100,
        "vertical_accuracy": 100,


Field Required? Type Description
latitude Required decimal The latitude of the geographic location in decimal degrees. Must range from -90 (the South Pole) to 90 (the North Pole).
longitude Required decimal The longitude of the geographic location in decimal degrees. Must range from -180 to 180.
altitude Optional decimal The altitude (in meters) of the geographic location. Can be negative.
horizontal_accuracy Optional decimal The horizontal accuracy (in meters) of the instrument providing this geolocation point. Must be >= 0.
vertical_accuracy Optional decimal The vertical accuracy (in meters) of the instrument providing this geolocation point. Must be >= 0.
Jump to Line
Something went wrong with that request. Please try again.