diff --git a/rocketapi/instagramapi.py b/rocketapi/instagramapi.py index cf8b55d..3809a21 100644 --- a/rocketapi/instagramapi.py +++ b/rocketapi/instagramapi.py @@ -26,6 +26,9 @@ def request(self, method, data): self.last_response = response self.counter += 1 if response["status"] == "done": + if method in ["instagram/media/get_shortcode_by_id", "instagram/media/get_id_by_shortcode"]: + return response + if ( response["response"]["status_code"] == 200 and response["response"]["content_type"] == "application/json" @@ -34,13 +37,22 @@ def request(self, method, data): elif response["response"]["status_code"] == 404: raise NotFoundException("Instagram resource not found") else: - raise BadResponseException("Bad response from Instagram") - raise BadResponseException("Bad response from RocketAPI") + raise BadResponseException( + f"Bad response from Instagram ({method}: {response['response']['status_code']})" + ) + raise BadResponseException(f"Bad response from RocketAPI ({method})") def search(self, query): """ Search for a specific user, hashtag or place. + As of September 2024, we no longer recommend using this method, as it now only returns a maximum of 5 users and leaves the places and hashtags arrays empty. Instead, please use the separate methods: + - `search_users` + - `search_hashtags` + - `search_locations` + - `search_audios` + - `search_clips` + Args: query (str): The search query @@ -48,16 +60,30 @@ def search(self, query): """ return self.request("instagram/search", {"query": query}) + def get_web_profile_info(self, username): + """ + Retrieve user web profile information by username. + + Args: + username (str): Username + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/get_web_profile_info + """ + return self.request( + "instagram/user/get_web_profile_info", {"username": username} + ) + def get_user_info(self, username): """ Retrieve user information by username. + This is an alias for get_web_profile_info. Args: username (str): Username For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/get_info """ - return self.request("instagram/user/get_info", {"username": username}) + return self.get_web_profile_info(username) def get_user_info_by_id(self, user_id): """ @@ -76,7 +102,7 @@ def get_user_media(self, user_id, count=12, max_id=None): Args: user_id (int): User id - count (int): Number of media to retrieve (max: 50) + count (int): Number of media to retrieve (max: 12) max_id (str): Use for pagination You can use the `max_id` parameter to paginate through the media (take from the `next_max_id` field of the response). @@ -88,19 +114,38 @@ def get_user_media(self, user_id, count=12, max_id=None): payload["max_id"] = max_id return self.request("instagram/user/get_media", payload) - def get_user_clips(self, user_id, max_id=None): + def get_user_media_by_username(self, username, count=12, max_id=None): + """ + Retrieve user media by username. + + Args: + username (str): Username + count (int): Number of media to retrieve (max: 12) + max_id (str): Use for pagination + + You can use the `max_id` parameter to paginate through the media (take from the `next_max_id` field of the response). + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/get_media_by_username + """ + payload = {"username": username, "count": count} + if max_id is not None: + payload["max_id"] = max_id + return self.request("instagram/user/get_media_by_username", payload) + + def get_user_clips(self, user_id, count=12, max_id=None): """ Retrieve user clips (videos from "Reels" section) by id. Args: user_id (int): User id + count (int): Number of media to retrieve (max: 12) max_id (str): Use for pagination You can use the `max_id` parameter to paginate through the media (take from the `max_id` (!) field of the response). For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/get_clips """ - payload = {"id": user_id} + payload = {"id": user_id, "count": count} if max_id is not None: payload["max_id"] = max_id return self.request("instagram/user/get_clips", payload) @@ -178,7 +223,7 @@ def get_user_followers(self, user_id, count=12, max_id=None): Args: user_id (int): User id - count (int): Number of users to return (max: 100) + count (int): Number of users to return (max: 50) max_id (str): Use for pagination You can use the `max_id` parameter to paginate through followers (take from the `next_max_id` field of the response). @@ -284,24 +329,52 @@ def get_media_info_by_shortcode(self, shortcode): "instagram/media/get_info_by_shortcode", {"shortcode": shortcode} ) - def get_media_likes(self, shortcode, count=12, max_id=None): + def get_media_likes_by_shortcode(self, shortcode): """ - Retrieve media likes by media shortcode. + Retrieve up to 1000 media likes by media shortcode. Args: shortcode (str): Media shortcode - count (int): Number of likers to return (max: 50) - max_id (str): Use for pagination - You can use the `max_id` parameter to paginate through likers (take from the `next_max_id` field of the response). + Pagination is not supported for this endpoint. For more information, see documentation: https://docs.rocketapi.io/api/instagram/media/get_likes """ - payload = {"shortcode": shortcode, "count": count} - if max_id is not None: - payload["max_id"] = max_id + payload = {"shortcode": shortcode} return self.request("instagram/media/get_likes", payload) + def get_media_likes(self, shortcode, count=12, max_id=None): + """ + Retrieve up to 1000 media likes by media shortcode. + This is an alias for get_media_likes_by_shortcode. + + Note: The parameters count and max_id are kept for backward compatibility but are no longer supported. + + Args: + shortcode (str): Media shortcode + count (int): DEPRECATED - No longer supported + max_id (str): DEPRECATED - No longer supported + + Pagination is not supported for this endpoint. + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/media/get_likes + """ + # Ignoring count and max_id parameters as they're no longer supported + return self.get_media_likes_by_shortcode(shortcode) + + def get_media_likes_by_id(self, media_id): + """ + Retrieve up to 1000 media likes by media id. + + Args: + media_id (int): Media id + + Pagination is not supported for this endpoint. + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/media/get_likes_by_id + """ + return self.request("instagram/media/get_likes_by_id", {"id": media_id}) + def get_media_comments(self, media_id, can_support_threading=True, min_id=None): """ Retrieve media comments by media id. @@ -344,6 +417,17 @@ def get_media_id_by_shortcode(self, shortcode): "instagram/media/get_id_by_shortcode", {"shortcode": shortcode} ) + def get_media_id_by_share(self, share): + """ + Get media id by share code (for links like https://www.instagram.com/share/XXXxx356, where XXXxx356 is the share code). + + Args: + share (str): Share code + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/media/get_id_by_share + """ + return self.request("instagram/media/get_id_by_share", {"share": share}) + def get_guide_info(self, guide_id): """ Retrieve guide information by guide id. @@ -366,7 +450,7 @@ def get_location_info(self, location_id): """ return self.request("instagram/location/get_info", {"id": location_id}) - def get_location_media(self, location_id, page=None, max_id=None): + def get_location_media(self, location_id, page=None, max_id=None, tab=None): """ Retrieve location media by location id. @@ -374,6 +458,7 @@ def get_location_media(self, location_id, page=None, max_id=None): location_id (int): Location id page (int): Page number max_id (str): Use for pagination + tab (str): Tab name: recent, ranked (default: recent) In order to use pagination, you need to use both the `max_id` and `page` parameters. You can obtain these values from the response's `next_page` and `next_max_id` fields. @@ -384,6 +469,8 @@ def get_location_media(self, location_id, page=None, max_id=None): payload["page"] = page if max_id is not None: payload["max_id"] = max_id + if tab is not None: + payload["tab"] = tab return self.request("instagram/location/get_media", payload) def get_hashtag_info(self, name): @@ -397,7 +484,7 @@ def get_hashtag_info(self, name): """ return self.request("instagram/hashtag/get_info", {"name": name}) - def get_hashtag_media(self, name, page=None, max_id=None): + def get_hashtag_media(self, name, page=None, max_id=None, tab=None): """ Retrieve hashtag media by hashtag name. @@ -405,6 +492,7 @@ def get_hashtag_media(self, name, page=None, max_id=None): name (str): Hashtag name page (int): Page number max_id (str): Use for pagination + tab (str): Tab name: recent, top, or clips (default: recent) In order to use pagination, you need to use both the `max_id` and `page` parameters. You can obtain these values from the response's `next_page` and `next_max_id` fields. @@ -415,6 +503,8 @@ def get_hashtag_media(self, name, page=None, max_id=None): payload["page"] = page if max_id is not None: payload["max_id"] = max_id + if tab is not None: + payload["tab"] = tab return self.request("instagram/hashtag/get_media", payload) def get_highlight_stories_bulk(self, highlight_ids): @@ -491,16 +581,102 @@ def get_audio_media(self, audio_id, max_id=None): payload["max_id"] = max_id return self.request("instagram/audio/get_media", payload) + def get_audio_media_by_canonical_id(self, audio_canonical_id, max_id=None): + """ + Retrieve audio media by audio canonical id. + + Args: + audio_canonical_id (int): Audio canonical id + max_id (str): Use for pagination + + You can use the `max_id` parameter to paginate through media (take from the `next_max_id` field of the response). + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/audio/get_media_by_canonical_id + """ + payload = {"id": audio_canonical_id} + if max_id is not None: + payload["max_id"] = max_id + return self.request("instagram/audio/get_media_by_canonical_id", payload) + + def get_live_info(self, broadcast_id): + """ + Retrieve live information by broadcast id. + + Args: + broadcast_id (int): Broadcast id + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/live/get_info + """ + return self.request("instagram/live/get_info", {"id": broadcast_id}) + def get_user_about(self, user_id): """ Obtain user details from «About this Account» section. - ⭐️ This method is exclusively available to our Enterprise+ clients. - If you wish to enable it for your account, please get in touch with our support team: https://t.me/rocketapi - Args: user_id (int): User id For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/get_about """ return self.request("instagram/user/get_about", {"id": user_id}) + + def search_users(self, query): + """ + Search for a specific user (max 50 results) + + Args: + query (str): The search query + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/user/search + """ + return self.request("instagram/user/search", {"query": query}) + + def search_hashtags(self, query): + """ + Search for a specific hashtag (max 20 results) + + Args: + query (str): The search query + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/hashtag/search + """ + return self.request("instagram/hashtag/search", {"query": query}) + + def search_locations(self, query): + """ + Search for a specific location (max 20 results) + + Args: + query (str): The search query + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/location/search + """ + return self.request("instagram/location/search", {"query": query}) + + def search_audios(self, query): + """ + Search for a specific audio (max 10 results) + + Args: + query (str): The search query + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/audio/search + """ + return self.request("instagram/audio/search", {"query": query}) + + def search_clips(self, query, max_id=None): + """ + Search for a specific clip with a caption that includes the query (max 12 results) + + Args: + query (str): The search query + max_id (str): Use for pagination + + You can use the max_id parameter to paginate through following (take from the reels_max_id field of the response). + + For more information, see documentation: https://docs.rocketapi.io/api/instagram/media/search_clips + """ + payload = {"query": query} + if max_id is not None: + payload["max_id"] = max_id + return self.request("instagram/media/search_clips", payload) diff --git a/rocketapi/rocketapi.py b/rocketapi/rocketapi.py index 8edd35a..02c776e 100644 --- a/rocketapi/rocketapi.py +++ b/rocketapi/rocketapi.py @@ -11,6 +11,7 @@ def __init__(self, token, max_timeout=30): For more information, see documentation: https://docs.rocketapi.io/api/ """ self.base_url = "https://v1.rocketapi.io/" + self.version = "1.0.12" self.token = token self.max_timeout = max_timeout @@ -18,6 +19,9 @@ def request(self, method, data): return requests.post( url=self.base_url + method, json=data, - headers={"Authorization": f"Token {self.token}"}, + headers={ + "Authorization": f"Token {self.token}", + "User-Agent": f"RocketAPI Python SDK/{self.version}", + }, timeout=self.max_timeout, ).json() diff --git a/setup.py b/setup.py index 29a2abe..1dbcf2b 100644 --- a/setup.py +++ b/setup.py @@ -3,12 +3,12 @@ setuptools.setup( name="rocketapi", - version="1.0.5", + version="1.0.12", author="RocketAPI", author_email="developer@rocketapi.io", description="RocketAPI Python SDK", packages=["rocketapi"], url="https://github.com/rocketapi-io/rocketapi-python", - download_url="https://github.com/rocketapi-io/rocketapi-python/archive/refs/tags/v1.0.5.tar.gz", + download_url="https://github.com/rocketapi-io/rocketapi-python/archive/refs/tags/v1.0.12.tar.gz", install_requires=["requests"], )