Annotated tweets

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 use. 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)

Creating a tweet with annotations:

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.

Type Guidelines

Some description of types...

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

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

song

artist

year

genre

movie

director

year

tv_show

network 

book

isbn 

author

year

product

manufacturer

model

price

stock

symbol

offer

holder 

topic

holder