Instagram Structures¶

Contents

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

context (InstaloaderContext) – Instaloader.context used for additional queries if neccessary..
node (Dict[str, Any]) – Node structure, as returned by Instagram.
owner_profile (Optional[Profile]) – The Profile of the owner, if already known at creation.

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

classmethod from_iphone_struct(context, media)¶: Create a post from a given iphone_struct.

New in version 4.9.

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 title¶

Title of post

Return type: Optional[str]

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

Changed in version 4.9: Return timezone aware datetime object.

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

property mediacount¶

The number of media in a sidecar Post, or 1 if the Post it not a sidecar.

New in version 4.6.

Return type: int

get_is_videos()¶

Return a list containing the is_video property for each media in the post.

New in version 4.7.

Return type: List[bool]

get_sidecar_nodes(start=0, end=-1)¶

Sidecar nodes of a Post with typename==GraphSidecar.

Changed in version 4.6: Added parameters start and end to specify a slice of sidecar media.

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 accessibility_caption¶

Accessibility caption of the post, if available.

New in version 4.9.

Return type: Optional[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.

Changed in version 4.7: Change return type to Iterable.

Return type: Iterable[PostComment]

get_likes()¶

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

Changed in version 4.5.4: Require being logged in (as required by Instagram).

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]

property is_pinned¶

True if this Post has been pinned by at least one user.

Return type: bool

Additionally, the following trivial structures are defined:

class PostSidecarNode¶

Item of a Sidecar Post.

is_video¶: Whether this node is a video.

display_url¶: URL of image or video thumbnail.

video_url¶: URL of video or None.

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

id¶: ID number of comment.

created_at_utc¶: datetime when comment was created (UTC).

text¶: Comment text.

owner¶: Owner Profile of the comment.

likes_count¶: Number of likes on comment.

answers¶: Iterator which yields all PostCommentAnswers for the comment.

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

id¶: ID number of comment.

created_at_utc¶: datetime when comment was created (UTC).

text¶: Comment text.

owner¶: Owner Profile of the comment.

likes_count¶: Number of likes on comment.

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

id¶: ID number of location.

name¶: Location name.

slug¶: URL friendly variant of location name.

has_public_page¶: Whether location has a public page.

lat¶: Latitude (float or None).

lng¶: Longitude (float or None).

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

context (InstaloaderContext) – InstaloaderContext instance used for additional queries if necessary.
node (Dict[str, Any]) – Dictionary containing the available information of the story as returned by Instagram.

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 of the most recent StoryItem that has been watched or None (local time zone).

Return type: Optional[datetime]

property last_seen_utc¶

Timestamp of the most recent StoryItem that has 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

context (InstaloaderContext) – InstaloaderContext instance used for additional queries if necessary.
node (Dict[str, Any]) – Dictionary containing the available information of the story item.
owner_profile (Optional[Profile]) – Profile instance representing the story owner.

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

classmethod from_mediaid(context, mediaid)¶: Create a StoryItem object from a given mediaid.

New in version 4.9.

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

Changed in version 4.9: Return timezone aware datetime object.

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 caption¶

Caption.

New in version 4.10.

Return type: Optional[str]

property caption_hashtags¶

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

New in version 4.10.

Return type: List[str]

property caption_mentions¶

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

New in version 4.10.

Return type: List[str]

property pcaption¶

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

New in version 4.10.

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

context (InstaloaderContext) – InstaloaderContext instance used for additional queries if necessary.
node (Dict[str, Any]) – Dictionary containing the available information of the highlight as returned by Instagram.
owner (Optional[Profile]) – Profile instance representing the owner profile of the highlight.

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 of the most recent StoryItem that has been watched or None (local time zone).

Return type: Optional[datetime]

property last_seen_utc¶

Timestamp of the most recent StoryItem that has 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.

Parameters

context (InstaloaderContext) – Instaloader.context
username (str) – Username

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

context (InstaloaderContext) – Instaloader.context
profile_id (int) – userid

Raises

ProfileNotExistsException

classmethod from_iphone_struct(context, media)¶: Create a profile from a given iphone_struct.

New in version 4.9.

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 biography_hashtags¶

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

New in version 4.10.

Return type: List[str]

property biography_mentions¶

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

New in version 4.10.

Return type: List[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

property profile_pic_url_no_iphone¶

Return URL of lower-quality profile picture.

New in version 4.9.3.

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_followed_hashtags()¶

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

Return type: NodeIterator[Hashtag]

New in version 4.10.

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.

Changed in version 4.9: Removed get_related_tags() and is_top_media_only as these features were removed from Instagram.

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

context (InstaloaderContext) – Instaloader.context
name (str) – Hashtag, without preceeding ‘#’

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: Optional[str]

property allow_following¶

Return type: bool

property is_following¶

Return type: bool

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 recent posts associated with this hashtag.

Deprecated since version 4.9: Use Hashtag.get_posts_resumable() as this method may return incorrect results (Issue #1457)

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]

get_posts_resumable()¶

Get the recent posts of the hashtag in a resumable fashion.

Return type: NodeIterator[Post]

New in version 4.9.

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

context (InstaloaderContext) – Instaloader.context used to send the query for the search.
searchstring (str) – String to search for with Instagram’s “top search”.

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(context, json_structure)¶

Loads a Post, Profile, StoryItem, Hashtag or FrozenNodeIterator from a json structure.

Parameters

context (InstaloaderContext) – Instaloader.context linked to the new object, used for additional queries if neccessary.
json_structure (dict) – Instaloader JSON structure

New in version 4.8.

Return type: Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]

load_structure_from_file(context, filename)¶

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

Parameters

context (InstaloaderContext) – Instaloader.context linked to the new object, used for additional queries if neccessary.
filename (str) – Filename, ends in ‘.json’ or ‘.json.xz’

Return type

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

get_json_structure(structure)¶

Returns Instaloader JSON structure for a Post, Profile, StoryItem, Hashtag: or FrozenNodeIterator so that it can be loaded by load_structure().

Parameters: structure (Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]) – Post, Profile, StoryItem or Hashtag

New in version 4.8.

Return type: dict

save_structure_to_file(structure, filename)¶

Saves a Post, Profile, StoryItem, Hashtag or FrozenNodeIterator 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

structure (Union[Post, Profile, StoryItem, Hashtag, FrozenNodeIterator]) – Post, Profile, StoryItem or Hashtag
filename (str) – Filename, ends in ‘.json’ or ‘.json.xz’

Return type

None

LatestStamps¶

class LatestStamps(latest_stamps_file)¶

LatestStamps class.

Convenience class for retrieving and storing data from the --latest-stamps file.

Parameters: latest_stamps_file – path to file.

New in version 4.8.

PROFILE_ID = 'profile-id'¶

PROFILE_PIC = 'profile-pic'¶

POST_TIMESTAMP = 'post-timestamp'¶

TAGGED_TIMESTAMP = 'tagged-timestamp'¶

IGTV_TIMESTAMP = 'igtv-timestamp'¶

STORY_TIMESTAMP = 'story-timestamp'¶

ISO_FORMAT = '%Y-%m-%dT%H:%M:%S.%f%z'¶

get_profile_id(profile_name)¶

Returns stored ID of profile.

Return type: Optional[int]

save_profile_id(profile_name, profile_id)¶: Stores ID of profile.

rename_profile(old_profile, new_profile)¶: Renames a profile.

get_last_post_timestamp(profile_name)¶

Returns timestamp of last download of a profile’s posts.

Return type: datetime

set_last_post_timestamp(profile_name, timestamp)¶: Sets timestamp of last download of a profile’s posts.

get_last_tagged_timestamp(profile_name)¶

Returns timestamp of last download of a profile’s tagged posts.

Return type: datetime

set_last_tagged_timestamp(profile_name, timestamp)¶: Sets timestamp of last download of a profile’s tagged posts.

get_last_igtv_timestamp(profile_name)¶

Returns timestamp of last download of a profile’s igtv posts.

Return type: datetime

set_last_igtv_timestamp(profile_name, timestamp)¶: Sets timestamp of last download of a profile’s igtv posts.

get_last_story_timestamp(profile_name)¶

Returns timestamp of last download of a profile’s stories.

Return type: datetime

set_last_story_timestamp(profile_name, timestamp)¶: Sets timestamp of last download of a profile’s stories.

get_profile_pic(profile_name)¶

Returns filename of profile’s last downloaded profile pic.

Return type: str

set_profile_pic(profile_name, profile_pic)¶: Sets filename of profile’s last downloaded profile pic.

Next Section

Resumable Iterations