0
# Legacy API (v1.1)
1
2
The API class provides complete access to Twitter API v1.1 endpoints for backward compatibility and access to v1.1-specific functionality not yet available in v2. This interface is considered legacy but remains important for certain features.
3
4
## Capabilities
5
6
### API Initialization
7
8
Create an API instance with authentication and configuration options.
9
10
```python { .api }
11
class API:
12
def __init__(self, auth=None, *, cache=None, host='api.twitter.com',
13
parser=None, proxy=None, retry_count=0, retry_delay=0,
14
retry_errors=None, timeout=60, upload_host='upload.twitter.com',
15
user_agent=None, wait_on_rate_limit=False):
16
"""
17
Initialize Twitter API v1.1 interface.
18
19
Parameters:
20
- auth (AuthHandler): Authentication handler object
21
- cache (Cache, optional): Cache implementation
22
- host (str): API host (default: 'api.twitter.com')
23
- parser (Parser, optional): Response parser
24
- proxy (str, optional): Proxy server URL
25
- retry_count (int): Number of retries on failure
26
- retry_delay (int): Delay between retries in seconds
27
- retry_errors (list, optional): HTTP status codes to retry
28
- timeout (int): Request timeout in seconds
29
- upload_host (str): Media upload host
30
- user_agent (str, optional): Custom user agent string
31
- wait_on_rate_limit (bool): Wait when rate limited
32
"""
33
```
34
35
### Timeline Methods
36
37
Access various Twitter timelines and user tweet collections.
38
39
```python { .api }
40
def home_timeline(self, *, count=20, since_id=None, max_id=None, trim_user=False,
41
exclude_replies=False, include_entities=True):
42
"""
43
Get the authenticated user's home timeline.
44
45
Parameters:
46
- count (int): Number of tweets to retrieve (max 200)
47
- since_id (int, optional): Return results after this tweet ID
48
- max_id (int, optional): Return results before this tweet ID
49
- trim_user (bool): Trim user objects to just ID
50
- exclude_replies (bool): Exclude reply tweets
51
- include_entities (bool): Include tweet entities
52
53
Returns:
54
List of Status objects (tweets)
55
"""
56
57
def user_timeline(self, *, user_id=None, screen_name=None, count=20,
58
since_id=None, max_id=None, trim_user=False,
59
exclude_replies=False, include_rts=True):
60
"""
61
Get tweets from a specific user's timeline.
62
63
Parameters:
64
- user_id (int, optional): User ID
65
- screen_name (str, optional): Username
66
- count (int): Number of tweets to retrieve (max 200)
67
- since_id (int, optional): Return results after this tweet ID
68
- max_id (int, optional): Return results before this tweet ID
69
- trim_user (bool): Trim user objects to just ID
70
- exclude_replies (bool): Exclude reply tweets
71
- include_rts (bool): Include retweets
72
73
Returns:
74
List of Status objects (tweets)
75
"""
76
77
def mentions_timeline(self, *, count=20, since_id=None, max_id=None,
78
trim_user=False, include_entities=True):
79
"""
80
Get tweets mentioning the authenticated user.
81
82
Returns:
83
List of Status objects (mention tweets)
84
"""
85
```
86
87
### Tweet Methods
88
89
Create, retrieve, and manage tweets using v1.1 endpoints.
90
91
```python { .api }
92
def update_status(self, status, *, in_reply_to_status_id=None,
93
auto_populate_reply_metadata=False, exclude_reply_user_ids=None,
94
attachment_url=None, media_ids=None, possibly_sensitive=False,
95
lat=None, long=None, place_id=None, display_coordinates=False,
96
trim_user=False, enable_dmcommands=False, fail_dmcommands=False,
97
card_uri=None):
98
"""
99
Post a new tweet.
100
101
Parameters:
102
- status (str): Tweet text content
103
- in_reply_to_status_id (int, optional): Tweet ID to reply to
104
- media_ids (list, optional): List of media IDs to attach
105
- possibly_sensitive (bool): Mark as potentially sensitive
106
- lat (float, optional): Latitude for geo location
107
- long (float, optional): Longitude for geo location
108
- place_id (str, optional): Place ID for location
109
110
Returns:
111
Status object (created tweet)
112
"""
113
114
def get_status(self, id, *, trim_user=False, include_my_retweet=True,
115
include_entities=True, include_ext_alt_text=True,
116
include_card_uri=False):
117
"""
118
Get a specific tweet by ID.
119
120
Parameters:
121
- id (int): Tweet ID
122
- trim_user (bool): Trim user objects to just ID
123
- include_my_retweet (bool): Include authenticated user's retweet
124
- include_entities (bool): Include tweet entities
125
126
Returns:
127
Status object (tweet)
128
"""
129
130
def destroy_status(self, id, *, trim_user=False):
131
"""
132
Delete a tweet.
133
134
Parameters:
135
- id (int): Tweet ID to delete
136
137
Returns:
138
Status object (deleted tweet)
139
"""
140
141
def retweet(self, id, *, trim_user=False):
142
"""
143
Retweet a tweet.
144
145
Returns:
146
Status object (retweet)
147
"""
148
149
def unretweet(self, id, *, trim_user=False):
150
"""
151
Remove a retweet.
152
153
Returns:
154
Status object (original tweet)
155
"""
156
```
157
158
### User Methods
159
160
Retrieve and manage user information and relationships.
161
162
```python { .api }
163
def get_user(self, *, user_id=None, screen_name=None, include_entities=True):
164
"""
165
Get user information by ID or screen name.
166
167
Parameters:
168
- user_id (int, optional): User ID
169
- screen_name (str, optional): Username
170
- include_entities (bool): Include user entities
171
172
Returns:
173
User object
174
"""
175
176
def lookup_users(self, *, user_ids=None, screen_names=None, include_entities=True,
177
tweet_mode="compat"):
178
"""
179
Get multiple users by IDs or screen names.
180
181
Parameters:
182
- user_ids (list, optional): List of user IDs (up to 100)
183
- screen_names (list, optional): List of usernames (up to 100)
184
185
Returns:
186
List of User objects
187
"""
188
189
def search_users(self, q, *, count=20, page=1, include_entities=True):
190
"""
191
Search for users.
192
193
Parameters:
194
- q (str): Search query
195
- count (int): Number of results per page (max 20)
196
- page (int): Page number
197
198
Returns:
199
List of User objects
200
"""
201
202
def create_friendship(self, *, user_id=None, screen_name=None, follow=True):
203
"""
204
Follow a user.
205
206
Parameters:
207
- user_id (int, optional): User ID to follow
208
- screen_name (str, optional): Username to follow
209
- follow (bool): Enable notifications
210
211
Returns:
212
User object (followed user)
213
"""
214
215
def destroy_friendship(self, *, user_id=None, screen_name=None):
216
"""
217
Unfollow a user.
218
219
Returns:
220
User object (unfollowed user)
221
"""
222
```
223
224
### Search Methods
225
226
Search for tweets and users using v1.1 search endpoints.
227
228
```python { .api }
229
def search_tweets(self, q, *, geocode=None, lang=None, locale=None,
230
result_type="mixed", count=15, until=None, since_id=None,
231
max_id=None, include_entities=True):
232
"""
233
Search for tweets.
234
235
Parameters:
236
- q (str): Search query
237
- geocode (str, optional): Geographic search ("lat,long,radius")
238
- lang (str, optional): Language code
239
- result_type (str): "mixed", "recent", or "popular"
240
- count (int): Number of results (max 100)
241
- until (str, optional): Search until date (YYYY-MM-DD)
242
- since_id (int, optional): Return results after this tweet ID
243
- max_id (int, optional): Return results before this tweet ID
244
245
Returns:
246
SearchResults object with tweets and metadata
247
"""
248
```
249
250
### List Methods
251
252
Manage Twitter lists using v1.1 list endpoints.
253
254
```python { .api }
255
def create_list(self, name, *, mode="public", description=None):
256
"""
257
Create a new list.
258
259
Parameters:
260
- name (str): List name
261
- mode (str): "public" or "private"
262
- description (str, optional): List description
263
264
Returns:
265
List object
266
"""
267
268
def get_list(self, *, list_id=None, slug=None, owner_screen_name=None,
269
owner_id=None):
270
"""
271
Get list information.
272
273
Returns:
274
List object
275
"""
276
277
def get_lists(self, *, user_id=None, screen_name=None, reverse=False):
278
"""
279
Get lists owned by a user.
280
281
Returns:
282
List of List objects
283
"""
284
285
def list_timeline(self, *, list_id=None, slug=None, owner_screen_name=None,
286
owner_id=None, count=20, since_id=None, max_id=None,
287
include_entities=True, include_rts=True):
288
"""
289
Get tweets from a list.
290
291
Returns:
292
List of Status objects
293
"""
294
```
295
296
### Media Upload Methods
297
298
Upload media files for use in tweets.
299
300
```python { .api }
301
def media_upload(self, filename, *, file=None, chunked=False,
302
media_category=None, additional_owners=None):
303
"""
304
Upload media file.
305
306
Parameters:
307
- filename (str): Path to media file
308
- file (file-like, optional): File object
309
- chunked (bool): Use chunked upload for large files
310
- media_category (str, optional): Media category
311
- additional_owners (list, optional): Additional owner user IDs
312
313
Returns:
314
Media object with media_id
315
"""
316
317
def chunked_upload(self, filename, *, file=None, file_type=None,
318
media_category=None, additional_owners=None):
319
"""
320
Upload large media file in chunks.
321
322
Returns:
323
Media object with media_id
324
"""
325
```
326
327
## Usage Examples
328
329
### Basic API Usage
330
331
```python
332
import tweepy
333
334
# Initialize with authentication
335
auth = tweepy.OAuth1UserHandler(
336
consumer_key="your_consumer_key",
337
consumer_secret="your_consumer_secret",
338
access_token="your_access_token",
339
access_token_secret="your_access_token_secret"
340
)
341
342
api = tweepy.API(auth, wait_on_rate_limit=True)
343
344
# Post a tweet
345
tweet = api.update_status("Hello from Tweepy v1.1 API!")
346
print(f"Posted tweet: {tweet.id}")
347
348
# Get home timeline
349
timeline = api.home_timeline(count=10)
350
for tweet in timeline:
351
print(f"@{tweet.user.screen_name}: {tweet.text}")
352
```
353
354
### Search and User Operations
355
356
```python
357
# Search for tweets
358
results = api.search_tweets(q="python programming", count=20, result_type="recent")
359
for tweet in results:
360
print(f"@{tweet.user.screen_name}: {tweet.text}")
361
362
# Get user information
363
user = api.get_user(screen_name="twitter")
364
print(f"User: {user.name} (@{user.screen_name})")
365
print(f"Followers: {user.followers_count:,}")
366
367
# Follow a user
368
api.create_friendship(screen_name="python")
369
print("Now following @python")
370
```
371
372
*Note: The API class contains hundreds of methods covering all Twitter API v1.1 endpoints. This documentation covers the most commonly used methods. Refer to the full Tweepy documentation for complete v1.1 API coverage.*