Instagram Structures

Posts

class Post(context, node, owner_profile=None)

Structure containing information about an Instagram post.

Created by methods Profile.get_posts(), Instaloader.get_hashtag_posts(), Instaloader.get_feed_posts() and Profile.get_saved_posts(), which return iterators of Posts:

L = Instaloader()
for post in L.get_hashtag_posts(HASHTAG):
    L.download_post(post, target='#'+HASHTAG)

Might also be created with:

post = Post.from_shortcode(L.context, SHORTCODE)

This class unifies access to the properties associated with a post. It implements == and is hashable.

Parameters
classmethod from_shortcode(context, shortcode)

Create a post object from a given shortcode

classmethod from_mediaid(context, mediaid)

Create a post object from a given mediaid

static shortcode_to_mediaid(code)
Return type

int

static mediaid_to_shortcode(mediaid)
Return type

str

static supported_graphql_types()

The values of __typename fields that the Post class can handle.

Return type

List[str]

property shortcode

Media shortcode. URL of the post is instagram.com/p/<shortcode>/.

Return type

str

property mediaid

The mediaid is a decimal representation of the media shortcode.

Return type

int

property owner_profile

Profile instance of the Post’s owner.

Return type

Profile

property owner_username

The Post’s lowercase owner name.

Return type

str

property owner_id

The ID of the Post’s owner.

Return type

int

property date_local

Timestamp when the post was created (local time zone).

Return type

datetime

property date_utc

Timestamp when the post was created (UTC).

Return type

datetime

property date

Synonym to date_utc

Return type

datetime

property profile

Synonym to owner_username

Return type

str

property url

URL of the picture / video thumbnail of the post

Return type

str

property typename

Type of post, GraphImage, GraphVideo or GraphSidecar

Return type

str

get_sidecar_nodes()

Sidecar nodes of a Post with typename==GraphSidecar.

Return type

Iterator[PostSidecarNode]

property caption

Caption.

Return type

Optional[str]

property caption_hashtags

List of all lowercased hashtags (without preceeding #) that occur in the Post’s caption.

Return type

List[str]

property caption_mentions

List of all lowercased profiles that are mentioned in the Post’s caption, without preceeding @.

Return type

List[str]

property pcaption

Printable caption, useful as a format specifier for –filename-pattern.

New in version 4.2.6.

Return type

str

property tagged_users

List of all lowercased users that are tagged in the Post.

Return type

List[str]

property is_video

True if the Post is a video.

Return type

bool

property video_url

URL of the video, or None.

Return type

Optional[str]

property video_view_count

View count of the video, or None.

New in version 4.2.6.

Return type

Optional[int]

property video_duration

Duration of the video in seconds, or None.

New in version 4.2.6.

Return type

Optional[float]

property viewer_has_liked

Whether the viewer has liked the post, or None if not logged in.

Return type

Optional[bool]

property likes

Likes count

Return type

int

property comments

Comment count including answers

Return type

int

get_comments()

Iterate over all comments of the post.

Each comment is represented by a PostComment namedtuple with fields text (string), created_at (datetime), id (int), owner (Profile) and answers (Iterator[PostCommentAnswer]) if available.

Return type

Iterator[PostComment]

get_likes()

Iterate over all likes of the post. A Profile instance of each likee is yielded.

Return type

Iterator[Profile]

property is_sponsored

Whether Post is a sponsored post, equivalent to non-empty Post.sponsor_users().

New in version 4.4.

Return type

bool

property sponsor_users

The Post’s sponsors.

New in version 4.4.

Return type

List[Profile]

property location

If the Post has a location, returns PostLocation namedtuple with fields ‘id’, ‘lat’ and ‘lng’ and ‘name’.

Changed in version 4.2.9: Require being logged in (as required by Instagram), return None if not logged-in.

Return type

Optional[PostLocation]

Additionally, the following trivial structures are defined:

class PostSidecarNode

Item of a Sidecar Post.

property display_url

URL of image or video thumbnail.

property is_video

Whether this node is a video.

property video_url

URL of video or None.

class PostComment(id, created_at_utc, text, owner, likes_count, answers)
property answers

Iterator which yields all PostCommentAnswers for the comment.

property created_at_utc

datetime when comment was created (UTC).

property id

ID number of comment.

property likes_count

Number of likes on comment.

property owner

Owner Profile of the comment.

property text

Comment text.

class PostCommentAnswer(id, created_at_utc, text, owner, likes_count)
property created_at_utc

datetime when comment was created (UTC).

property id

ID number of comment.

property likes_count

Number of likes on comment.

property owner

Owner Profile of the comment.

property text

Comment text.

class PostLocation(id, name, slug, has_public_page, lat, lng)
property has_public_page

Whether location has a public page.

property id

ID number of location.

property lat

Latitude (float).

property lng

Longitude (float).

property name

Location name.

property slug

URL friendly variant of location name.

User Stories

class Story(context, node)

Structure representing a user story with its associated items.

Provides methods for accessing story properties, as well as Story.get_items() to request associated StoryItem nodes. Stories are returned by Instaloader.get_stories().

With a logged-in Instaloader instance L, you may download all your visible user stories with:

for story in L.get_stories():
    # story is a Story object
    for item in story.get_items():
        # item is a StoryItem object
        L.download_storyitem(item, ':stories')

This class implements == and is hashable.

Parameters
property unique_id

This ID only equals amongst Story instances which have the same owner and the same set of StoryItem. For all other Story instances this ID is different.

Return type

Union[str, int]

property last_seen_local

Timestamp when the story has last been watched or None (local time zone).

Return type

Optional[datetime]

property last_seen_utc

Timestamp when the story has last been watched or None (UTC).

Return type

Optional[datetime]

property latest_media_local

Timestamp when the last item of the story was created (local time zone).

Return type

datetime

property latest_media_utc

Timestamp when the last item of the story was created (UTC).

Return type

datetime

property itemcount

Count of items associated with the Story instance.

Return type

int

property owner_profile

Profile instance of the story owner.

Return type

Profile

property owner_username

The story owner’s lowercase username.

Return type

str

property owner_id

The story owner’s ID.

Return type

int

get_items()

Retrieve all items from a story.

Return type

Iterator[StoryItem]

class StoryItem(context, node, owner_profile=None)

Structure containing information about a user story item i.e. image or video.

Created by method Story.get_items(). This class implements == and is hashable.

Parameters
property mediaid

The mediaid is a decimal representation of the media shortcode.

Return type

int

property shortcode

Convert mediaid to a shortcode-like string, allowing {shortcode} to be used with --filename-pattern.

Return type

str

property owner_profile

Profile instance of the story item’s owner.

Return type

Profile

property owner_username

The StoryItem owner’s lowercase name.

Return type

str

property owner_id

The ID of the StoryItem owner.

Return type

int

property date_local

Timestamp when the StoryItem was created (local time zone).

Return type

datetime

property date_utc

Timestamp when the StoryItem was created (UTC).

Return type

datetime

property date

Synonym to date_utc

Return type

datetime

property profile

Synonym to owner_username

Return type

str

property expiring_local

Timestamp when the StoryItem will get unavailable (local time zone).

Return type

datetime

property expiring_utc

Timestamp when the StoryItem will get unavailable (UTC).

Return type

datetime

property url

URL of the picture / video thumbnail of the StoryItem

Return type

str

property typename

Type of post, GraphStoryImage or GraphStoryVideo

Return type

str

property is_video

True if the StoryItem is a video.

Return type

bool

property video_url

URL of the video, or None.

Return type

Optional[str]

Highlights

class Highlight(context, node, owner=None)

Structure representing a user’s highlight with its associated story items.

Provides methods for accessing highlight properties, as well as Highlight.get_items() to request associated StoryItem nodes. Highlights are returned by Instaloader.get_highlights().

With a logged-in Instaloader instance L, you may download all highlights of a Profile instance USER with:

for highlight in L.get_highlights(USER):
    # highlight is a Highlight object
    for item in highlight.get_items():
        # item is a StoryItem object
        L.download_storyitem(item, '{}/{}'.format(highlight.owner_username, highlight.title))

This class implements == and is hashable.

Parameters

Bases: Story

New in version 4.1.

property unique_id

A unique ID identifying this set of highlights.

Return type

int

property owner_profile

Profile instance of the highlights’ owner.

Return type

Profile

property title

The title of these highlights.

Return type

str

property cover_url

URL of the highlights’ cover.

Return type

str

property cover_cropped_url

URL of the cropped version of the cover.

Return type

str

property itemcount

Count of items associated with the Highlight instance.

Return type

int

get_items()

Retrieve all associated highlight items.

Return type

Iterator[StoryItem]

property last_seen_local

Timestamp when the story has last been watched or None (local time zone).

Return type

Optional[datetime]

property last_seen_utc

Timestamp when the story has last been watched or None (UTC).

Return type

Optional[datetime]

property latest_media_local

Timestamp when the last item of the story was created (local time zone).

Return type

datetime

property latest_media_utc

Timestamp when the last item of the story was created (UTC).

Return type

datetime

property owner_id

The story owner’s ID.

Return type

int

property owner_username

The story owner’s lowercase username.

Return type

str

Profiles

class Profile(context, node)

An Instagram Profile.

Provides methods for accessing profile properties, as well as Profile.get_posts() and for own profile Profile.get_saved_posts().

Get instances with Post.owner_profile(), StoryItem.owner_profile(), Profile.get_followees(), Profile.get_followers() or:

L = Instaloader()
profile = Profile.from_username(L.context, USERNAME)

Provides Profile.get_posts() and for own profile Profile.get_saved_posts() to iterate over associated Post objects:

for post in profile.get_posts():
    L.download_post(post, target=profile.username)

Profile.get_followees() and Profile.get_followers():

print("{} follows these profiles:".format(profile.username))
for followee in profile.get_followees():
    print(followee.username)

Also, this class implements == and is hashable.

classmethod from_username(context, username)

Create a Profile instance from a given username, raise exception if it does not exist.

See also Instaloader.check_profile_id().

Parameters
Raises

ProfileNotExistsException

classmethod from_id(context, profile_id)

Create a Profile instance from a given userid. If possible, use Profile.from_username() or constructor directly rather than this method, since it requires more requests.

Parameters
Raises

ProfileNotExistsException

classmethod own_profile(context)

Return own profile if logged-in.

Parameters

context (InstaloaderContext) – Instaloader.context

New in version 4.5.2.

property userid

User ID

Return type

int

property username

Profile Name

Return type

str

property is_private
Return type

bool

property followed_by_viewer
Return type

bool

property mediacount
Return type

int

property igtvcount
Return type

int

property followers
Return type

int

property followees
Return type

int

property external_url
Return type

Optional[str]

property is_business_account

New in version 4.4.

Return type

bool

property business_category_name

New in version 4.4.

Return type

str

property biography
Return type

str

property blocked_by_viewer
Return type

bool

property follows_viewer
Return type

bool

property full_name
Return type

str

property has_blocked_viewer
Return type

bool

property has_highlight_reels

Deprecated since version 4.0.6: Always returns True since Issue #153.

Before broken, this indicated whether the Profile had available stories.

Return type

bool

property has_public_story
Return type

bool

property has_viewable_story

Deprecated since version 4.0.6.

Some stories are private. This property determines if the Profile has at least one story which can be viewed using the associated InstaloaderContext, i.e. the viewer has privileges to view it.

Return type

bool

property has_requested_viewer
Return type

bool

property is_verified
Return type

bool

property requested_by_viewer
Return type

bool

property profile_pic_url

Return URL of profile picture. If logged in, the HD version is returned, otherwise a lower-quality version.

New in version 4.0.3.

Changed in version 4.2.1: Require being logged in for HD version (as required by Instagram).

Return type

str

get_profile_pic_url()

Deprecated since version 4.0.3.

Use profile_pic_url.

Return type

str

get_posts()

Retrieve all posts from a profile.

Return type

NodeIterator[Post]

get_saved_posts()

Get Posts that are marked as saved by the user.

Return type

NodeIterator[Post]

get_tagged_posts()

Retrieve all posts where a profile is tagged.

Return type

NodeIterator[Post]

New in version 4.0.7.

get_igtv_posts()

Retrieve all IGTV posts.

Return type

NodeIterator[Post]

New in version 4.3.

get_followers()

Retrieve list of followers of given profile. To use this, one needs to be logged in and private profiles has to be followed.

Return type

NodeIterator[Profile]

get_followees()

Retrieve list of followees (followings) of given profile. To use this, one needs to be logged in and private profiles has to be followed.

Return type

NodeIterator[Profile]

get_similar_accounts()

Retrieve list of suggested / similar accounts for this profile. To use this, one needs to be logged in.

New in version 4.4.

Return type

Iterator[Profile]

Hashtags

class Hashtag(context, node)

An Hashtag.

Analogous to Profile, get an instance with:

L = Instaloader()
hashtag = Hashtag.from_name(L.context, HASHTAG)

To then download the Hashtag’s Posts, do:

for post in hashtag.get_posts():
   L.download_post(post, target="#"+hashtag.name)

Also, this class implements == and is hashable.

New in version 4.4.

classmethod from_name(context, name)

Create a Hashtag instance from a given hashtag name, without preceeding ‘#’. Raises an Exception if there is no hashtag with the given name.

Parameters
Raises

QueryReturnedNotFoundException

property name

Hashtag name lowercased, without preceeding ‘#’

property hashtagid
Return type

int

property profile_pic_url
Return type

str

property description
Return type

str

property allow_following
Return type

bool

property is_following
Return type

bool

property is_top_media_only
Return type

bool

Yields similar hashtags.

Return type

Iterator[Hashtag]

get_top_posts()

Yields the top posts of the hashtag.

Return type

Iterator[Post]

property mediacount

The count of all media associated with this hashtag.

The number of posts with a certain hashtag may differ from the number of posts that can actually be accessed, as the hashtag count might include private posts

Return type

int

get_posts()

Yields the posts associated with this hashtag.

Return type

Iterator[Post]

get_all_posts()

Yields all posts, i.e. all most recent posts and the top posts, in almost-chronological order.

Return type

Iterator[Post]

TopSearchResults

class TopSearchResults(context, searchstring)

An invocation of this class triggers a search on Instagram for the provided search string.

Provides methods to access the search results as profiles (Profile), locations (PostLocation) and hashtags.

Parameters

New in version 4.3.

get_profiles()

Provides the Profile instances from the search result.

Return type

Iterator[Profile]

get_prefixed_usernames()

Provides all profile names from the search result that start with the search string.

Return type

Iterator[str]

get_locations()

Provides instances of PostLocation from the search result.

Return type

Iterator[PostLocation]

get_hashtag_strings()

Provides the hashtags from the search result as strings.

Return type

Iterator[str]

get_hashtags()

Provides the hashtags from the search result.

New in version 4.4.

Return type

Iterator[Hashtag]

property searchstring

The string that was searched for on Instagram to produce this TopSearchResults instance.

Return type

str

Loading and Saving

Post, StoryItem, Profile, Hashtag and FrozenNodeIterator can be saved and loaded to/from JSON files.

load_structure_from_file(context, filename)

Loads a Post, Profile, StoryItem or Hashtag from a ‘.json’ or ‘.json.xz’ file that has been saved by save_structure_to_file().

Parameters
Return type

Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]

save_structure_to_file(structure, filename)

Saves a Post, Profile, StoryItem or Hashtag to a ‘.json’ or ‘.json.xz’ file such that it can later be loaded by load_structure_from_file().

If the specified filename ends in ‘.xz’, the file will be LZMA compressed. Otherwise, a pretty-printed JSON file will be created.

Parameters
Return type

None

Next Section

Resumable Iterations