Instagram Structures¶
Contents
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()
andProfile.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.
-
property
shortcode
¶ Media shortcode. URL of the post is instagram.com/p/<shortcode>/.
- Return type
-
property
date_local
¶ Timestamp when the post was created (local time zone).
Changed in version 4.9: Return timezone aware datetime object.
- Return type
-
property
profile
¶ Synonym to
owner_username
- Return type
-
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
-
get_is_videos
()¶ Return a list containing the
is_video
property for each media in the post.New in version 4.7.
-
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
List of all lowercased hashtags (without preceeding #) that occur in the Post’s caption.
-
property
caption_mentions
¶ List of all lowercased profiles that are mentioned in the Post’s caption, without preceeding @.
-
property
pcaption
¶ Printable caption, useful as a format specifier for –filename-pattern.
New in version 4.2.6.
- Return type
-
property
accessibility_caption
¶ Accessibility caption of the post, if available.
New in version 4.9.
-
property
tagged_users
¶ List of all lowercased users that are tagged in the Post.
-
property
video_view_count
¶ View count of the video, or None.
New in version 4.2.6.
-
property
video_duration
¶ Duration of the video in seconds, or None.
New in version 4.2.6.
-
property
viewer_has_liked
¶ Whether the viewer has liked the post, or None if not logged in.
-
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
-
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).
-
property
is_sponsored
¶ Whether Post is a sponsored post, equivalent to non-empty
Post.sponsor_users()
.New in version 4.4.
- Return type
-
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
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.
-
text
¶ Comment text.
-
likes_count
¶ Number of likes on comment.
-
answers
¶ Iterator which yields all
PostCommentAnswer
s for the comment.
-
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 associatedStoryItem
nodes. Stories are returned byInstaloader.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 ofStoryItem
. For all otherStory
instances this ID is different.
-
property
last_seen_local
¶ Timestamp of the most recent StoryItem that has been watched or None (local time zone).
-
property
last_seen_utc
¶ Timestamp of the most recent StoryItem that has been watched or None (UTC).
-
property
latest_media_local
¶ Timestamp when the last item of the story was created (local time zone).
- Return type
-
property
latest_media_utc
¶ Timestamp when the last item of the story was created (UTC).
- Return type
-
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
shortcode
¶ Convert
mediaid
to a shortcode-like string, allowing{shortcode}
to be used with--filename-pattern
.- Return type
-
classmethod
from_mediaid
(context, mediaid)¶ Create a StoryItem object from a given mediaid.
New in version 4.9.
-
property
date_local
¶ Timestamp when the StoryItem was created (local time zone).
Changed in version 4.9: Return timezone aware datetime object.
- Return type
-
property
profile
¶ Synonym to
owner_username
- Return type
-
property
expiring_local
¶ Timestamp when the StoryItem will get unavailable (local time zone).
- Return type
-
property
expiring_utc
¶ Timestamp when the StoryItem will get unavailable (UTC).
- Return type
List of all lowercased hashtags (without preceeding #) that occur in the StoryItem’s caption.
New in version 4.10.
-
property
caption_mentions
¶ List of all lowercased profiles that are mentioned in the StoryItem’s caption, without preceeding @.
New in version 4.10.
-
property
pcaption
¶ Printable caption, useful as a format specifier for –filename-pattern.
New in version 4.10.
- Return type
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 associatedStoryItem
nodes. Highlights are returned byInstaloader.get_highlights()
.With a logged-in
Instaloader
instance L, you may download all highlights of aProfile
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
last_seen_local
¶ Timestamp of the most recent StoryItem that has been watched or None (local time zone).
-
property
last_seen_utc
¶ Timestamp of the most recent StoryItem that has been watched or None (UTC).
-
property
latest_media_local
¶ Timestamp when the last item of the story was created (local time zone).
- Return type
-
property
latest_media_utc
¶ Timestamp when the last item of the story was created (UTC).
- Return type
Profiles¶
-
class
Profile
(context, node)¶ An Instagram Profile.
Provides methods for accessing profile properties, as well as
Profile.get_posts()
and for own profileProfile.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 profileProfile.get_saved_posts()
to iterate over associatedPost
objects:for post in profile.get_posts(): L.download_post(post, target=profile.username)
Profile.get_followees()
andProfile.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
context (
InstaloaderContext
) –Instaloader.context
username (
str
) – Username
- Raises
-
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
-
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.
List of all lowercased hashtags (without preceeding #) that occur in the Profile’s biography.
New in version 4.10.
-
property
biography_mentions
¶ List of all lowercased profiles that are mentioned in the Profile’s biography, without preceeding @.
New in version 4.10.
-
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
-
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 associatedInstaloaderContext
, i.e. the viewer has privileges to view it.- Return type
-
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
-
property
profile_pic_url_no_iphone
¶ Return URL of lower-quality profile picture.
New in version 4.9.3.
- Return type
-
get_profile_pic_url
()¶ Deprecated since version 4.0.3.
Use
profile_pic_url
.- Return type
-
get_posts
()¶ Retrieve all posts from a profile.
- Return type
-
get_saved_posts
()¶ Get Posts that are marked as saved by the user.
- Return type
-
get_tagged_posts
()¶ Retrieve all posts where a profile is tagged.
- Return type
New in version 4.0.7.
-
get_igtv_posts
()¶ Retrieve all IGTV posts.
- Return type
New in version 4.3.
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
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
-
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
-
classmethod
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_prefixed_usernames
()¶ Provides all profile names from the search result that start with the search string.
-
get_locations
()¶ Provides instances of
PostLocation
from the search result.- Return type
-
get_hashtag_strings
()¶ Provides the hashtags from the search result as strings.
-
property
searchstring
¶ The string that was searched for on Instagram to produce this
TopSearchResults
instance.- Return type
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
orFrozenNodeIterator
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.
-
load_structure_from_file
(context, filename)¶ Loads a
Post
,Profile
,StoryItem
,Hashtag
orFrozenNodeIterator
from a ‘.json’ or ‘.json.xz’ file that has been saved bysave_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 byload_structure()
.
- Parameters
structure (
Union
[Post
,Profile
,StoryItem
,Hashtag
,FrozenNodeIterator
]) –Post
,Profile
,StoryItem
orHashtag
New in version 4.8.
- Return type
- Returns Instaloader JSON structure for a
-
save_structure_to_file
(structure, filename)¶ Saves a
Post
,Profile
,StoryItem
,Hashtag
orFrozenNodeIterator
to a ‘.json’ or ‘.json.xz’ file such that it can later be loaded byload_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.
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'¶
-
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
-
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
-
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
-
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
-
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
-
set_profile_pic
(profile_name, profile_pic)¶ Sets filename of profile’s last downloaded profile pic.