Iterators¶

Twitter API has multiple endpoints that exposes pages api. The implementation might differ from endpoint to endpoint.
Tweetinvi hides this complexity to you via iterators.

When you see a tag iterators it informs you that the endpoint can be reached via an iterator.

Iterator¶

Iterators let you request multiple pages until no more items are available.

NextPageAsync() request twitter for the next page of results
NextCursor is updated after each call to NextPageAsync. It can be used to start a new request at this position.
Completed is updated after each call to NextPageAsync. It is marked as true when no more results are available.

Iterator page¶

Pages are enumerators and contain elements returned by a single request.

ToArray() returns the content of the page.
NextCursor contains the next cursor to use for following requests.
IsLastPage informs whether the page was the last one that could be reached.

Example¶

var timelineTweets = new List<ITweet>();
var timelineIterator = userClient.Timelines.GetHomeTimelineIterator();

while (!timelineIterator.Completed)
{
    var page = await timelineIterator.NextPageAsync(); 
    timelineTweets.AddRange(page);
}

Restart from a previous cursor¶

As mentioned you can restart from a previous cursor state.

var firstFriendIdsIterator = client.Users.GetFollowerIdsIterator(new GetFollowerIdsParameters("tweetinvi")
{
    PageSize = 50
});
var firstPage = await firstFriendIdsIterator.NextPageAsync();

After having retrieved a first page, we can now request a new one from the previous cursor.

var friendIdsIterator = client.Users.GetFollowerIdsIterator(new GetFollowerIdsParameters("tweetinvi")
{
    Cursor = firstFriendIdsIterator.NextCursor,
    // or Cursor = firstPage.NextCursor
});
var secondPage = await friendIdsIterator.NextPageAsync();

Flavour of iterators¶

As mentioned earlier Twitter exposes different support of pages. As a consequence parameters might differ between 2 types of iterator.

Cursor iterators¶

Cursor iterators accesses cursor endpoint properly supported by Twitter API

int PageSize defines the maximum number of items that will be returned per request.
string Cursor defines the cursor that will be used for executing the first request.

var friendIdsIterator = client.Users.GetFollowerIdsIterator(new GetFollowerIdsParameters("tweetinvi")
{
    Cursor = "previous_cursor",
    PageSize = 50
});

MinMax iterators¶

MinMax iterators accesses older api endpoints that have less reliable support for cursors

int PageSize defines the maximum number of items that will be returned per request.
long? SinceId defines the minimum id that can be returned by Twitter
long? MaxId defines the maximum id that can be returned by Twitter
ContinueMinMaxCursor defines when the cursor is considered complete. By default it will be considered complete when 0 results are being returned.

var timelineIterator = userClient.Timelines.GetHomeTimelineIterator(new GetHomeTimelineParameters()
{
    MaxId = 410984184018409,
    SinceId = 3109841840184091,
    PageSize = 50,
    ContinueMinMaxCursor = ContinueMinMaxCursor.UntilNoItemsReturned
});

Multi-Levels iterators¶

Twitter API misses some useful endpoints. Tweetinvi created multi level cursors that takes care of handling the complexity for you

Twitter do not provide any endpoint to retrieve a collection of friends. It only supports retrieving friend ids.
The Users.GetFollowersIterator is an example of a multi level cursor and is used exactly as other cursors.

var friendsIterator = client.Users.GetFollowersIterator(new GetFollowersParameters("tweetinvi"));
while (!friendsIterator.Completed)
{
    var page = await friendsIterator.NextPageAsync(); 
}

Here is what happens behind the scenes when a user has more than 5000 friends:

1st call to await friendsIterator.NextPageAsync();, Tweetinvi performs 2 requests and returns 100 users.
- GetFriendIds that return 5000 friend ids
- GetUsers that return 100 users
Next 49x calls to await friendsIterator.NextPageAsync();; Tweetinvi 1 request to get the next users.
- GetUsers that return 100 users
On the 51st call to await friendsIterator.NextPageAsync();; Tweetinvi performs again 2 requests.
- GetFriendIds that return 5000 friend ids
- GetUsers that return 100 users