Tweets with annotations

When you create a tweet, you can add one or more annotations to that tweet. These annotations represent structured metadata about the tweet. What that metadata contains is up to you. The feature simply provides a structure for how to specify the annotations and retrieve them along with the tweet.

A tweet can have one or more annotations. An annotation is a tuple whose first element is a 'type' and whose second element is one or more attribute names with values. Here are some examples of various annotations represented in JSON and in a simple custom format:

A single annotation of type 'type', with a single attribute named 'attribute' whose value is 'value':

  JSON:
  "annotations":[{"type":{"attribute":"value"}}]
 
  Simple format:
  type:attribute=value

A single annotationn of type 'type', with two attributes, one called 'attribute' and the other called 'another_attribute', both of whose values are 'value:
 
  JSON:
  "annotations":
    [{"type":{"another_attribute":"value", "attribute":"value"}}]
    
  Simple format:
  type:attribute=value&another_attribute=value
 
Two annotations, one of type 'type', the other of type 'another_type', each of which has two attributes:

  JSON:
  "annotations":
    [{"type":{"another_attribute":"value", "attribute":"value"}},
     {"another_type":{"another_attribute":"value", "attribute":"value"}}]
 
  Simple format:
  type:attribute=value&another_attribute=value,another_type:attribute=value&another_attribute=value
 
Two annotations, both of which happen to be of type 'type' (this is allowed), each of which have two attributes:

  JSON:
  "annotations":
    [{"type":{"another_attribute":"value", "attribute":"value"}},
     {"type":{"another_attribute":"value", "attribute":"value"}}]

  Simple format:
  type:attribute=value&another_attribute=value,type:attribute=value&another_attribute=value

To summarize:

•   a tweet can have one or more annotation
•   tweets can have more than one annotation of the same type
•   annotations of the same type are still separate annotations
•   the attribute names in a given annotation may only occur once in a given annotation (the same restrictions as a conventional hash map)

Limits:

• when you sum up all the bytes that make up all your annotation types, attribute names and attribute values, the total size of bytes must be no more than 512 bytes (we're hoping to increase this over time as capacity permits to something closer to 2K)

Annotations are posted to /statuses/update.format with the "annotations" parameter. You can specify the annotations in JSON (as above) or using the simple custom format (as above).

On successful status creation, the status payload response will contain the annotations.

The annotation portion of a status payload will look like the following examples:

XML:
<annotations type="array">
  <annotation>
    <type>foo</type>
    <attributes>
      <attribute>
        <name>bar</name>
        <value>baz</value>
      </attribute>
    </attributes>
  </annotation>
</annotations>

JSON:
"annotations":[{"foo":{"bar":"baz"}}]

Error cases:

•   An annotations payload that is too large will return an error response.
•   JSON annotations submitted that are structured incorrectly will also return an error response.

Annotations Formatter:

Raffi made an annotations formatter which you may find helpful. 

Annotation Guidelines

The goal of Annotations are to bring more structured data to tweets to allow for better discovery of data and richer interactions. We aim to borrow heavily from, and use when possible, existing standards like RDFa, Microformats, Open Graph Protocol, AB Meta and Activitystrea.ms. Annotations will be a community-driven effort, but we aim to offer some initial guidance to hopefully create a critical mass of data that benefits users and developers. We want to lean towards loose-typing and minimal requirements while balancing that with enough structure to determine some semantics about the content or expression.

These are still very rough and are subject to drastic changes.

Common Attributes

Any annotations that present these will be recommended to be displayed along with the tweet. We will recommend for all clients that they render at least these attributes to users

title 

image

url

Attributes with special treatment

text 

audio_url

video_url

activity

Recommended Types

webpage

title 

image

url

place

a "place" can have any combination of the attributes depending on how you are trying to represent the user's location. For instance 

id

provider

place_type

street_address

locality

region

postal_code

country_code

latitude

longitude

review

content

rating

song

artist

year

genre

album

movie

director

year

tvshow

network 

book

isbn 

author

year

product

brand

model

price

category

stock

symbol

offer

holder 

topic

holder 

event

location 

start_date

end_date