New Withheld Content Fields in API Responses

Thursday, 26 January 2012

Updated on Nov. 2, 2012 to reflect the changes announced in Changes to withheld content fields and More changes to withheld content fields.

The Twitter REST API will soon return new data attributes to accommodate specific circumstances in which Twitter is required to withhold certain content in particular countries. We provide more detail on this on our Twitter blog and our Support pages.

The new attributes, withheld_in_countries and withheld_scope, will denote which countries the Tweet or the account is being withheld in, as well as the the scope of the data being withheld: at the Tweet level or at the user account level. Furthermore, if we believe the API request itself comes from a country in which that Tweet or account has been withheld, then the Tweet text and/or the user data will be replaced with text indicating it has been withheld.

For instance, if a specific Tweet is withheld in a country, the key-value pairs for “text”, “withheld_in_countries”, and “withheld_scope” will appear in the JSON response body for GET statuses/show (the XML format will be affected as well, though not Atom or RSS at this time) as shown below. So, if a Tweet were theoretically withheld in Japan, the response would include:

 "text": "This Tweet from @chatty is withheld in: Japan.",

```
 "withheld_scope": "status",
```
```
 "withheld_in_countries": ["JP"],
```

If a request is made for a Tweet by a user account that is being withheld in a certain country, then all of the aforementioned key-value pairs still apply, plus the user information is also altered to denote that it has been withheld.

"text": "@chatty's account is withheld in: Greece, Hong Kong, Malaysia,.",

```
"withheld_scope": "user",
```

"withheld_in_countries": ["GR", "HK", "MY"],

```
"name": "Withheld account",
```
```
"screen_name": "chatty",
```
```
"location": null,
```

"description": "This account is withheld in: Greece, Hong Kong, Malaysia,",

Lastly, if a user account is being withheld in a specific country, then the following key-value pairs will appear as such in the API response for GET users/show:

"text": "This Tweet from @chatty is withheld in: Argentina, Germany.",

```
"withheld_scope": "user",
```
```
"withheld_in_countries": ["AR", "DE"],
```

```
"name": "Withheld account",
```
```
"screen_name": "chatty",
```
```
"location": null, 
```

"description": "This account is withheld in: Argentina, Germany."

This change has not yet been implemented in the Streaming API, but you should expect to see this implemented there in the near future. For more information on how Country Withheld Content works and the reasoning behind it, please read our Blog post and Support FAQ.