getsocialapi-instagram 0.1.0__tar.gz

getsocialapi_instagram-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GetSocialAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

getsocialapi_instagram-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: getsocialapi-instagram
+Version: 0.1.0
+Summary: GetSocialAPI — client library for the Instagram API (no cookies, no accounts required)
+Author: GetSocialAPI
+License: MIT
+Project-URL: Homepage, https://getsocialapi.com
+Project-URL: Documentation, https://getsocialapi.com/docs/
+Keywords: instagram,api,scraping,sdk,getsocialapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# Instagram Scraper API
+
+[![tests](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml/badge.svg)](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)
+
+Python client for the **[GetSocialAPI](https://getsocialapi.com/)** Instagram Scraper API.
+
+- **No cookies required** — you never provide Instagram session cookies
+- **No accounts needed** — zero ban risk for your own profiles
+- Raw Instagram JSON responses, REST endpoints — no transformations
+- Automatic retries with `Retry-After`, typed exceptions
+
+## Installation
+
+```bash
+pip install getsocialapi-instagram
+```
+
+## Migration from `getsocialapi` (git installs)
+
+Before the PyPI release this SDK was installed from git as `getsocialapi`.
+Old imports keep working via a deprecated shim, but please migrate:
+
+```bash
+pip uninstall getsocialapi
+pip install getsocialapi-instagram
+```
+
+```python
+# before
+from getsocialapi import Client
+# after
+from getsocialapi_instagram import Client
+```
+
+## Quickstart
+
+```python
+from getsocialapi_instagram import Client
+
+# Get your API key at https://getsocialapi.com/dashboard/
+client = Client(api_key="gsa_live_...")  # or set GETSOCIALAPI_API_KEY
+
+# Profile by numeric id (or user_by_username for usernames)
+user = client.instagram.user_info(25025320)
+print(user["user"]["follower_count"])
+
+# Posts (grid)
+medias = client.instagram.user_medias(25025320, count=12)
+
+# Followers / following — paginated on unverified accounts: pass `next_max_id`
+# back as `max_id`. Verified accounts (blue checkmark) expose ~50 followers max.
+page = client.instagram.followers(43586162288, count=25)
+page = client.instagram.followers(43586162288, max_id=page["next_max_id"])
+
+# All comments of a post — cursor is next_min_id -> min_id (sort_order="recent" by default)
+comments, cursor = [], None
+while True:
+    page = client.instagram.media_comments(4012386322294878415, count=50, min_id=cursor)
+    comments += page["comments"]
+    cursor = page.get("next_min_id")
+    if not cursor:
+        break
+```
+
+Base URL: `https://api.getsocialapi.com/v1` — authenticate with the API key
+from your [dashboard](https://getsocialapi.com/dashboard/).
+
+## Client
+
+```python
+Client(api_key=None, base_url="https://api.getsocialapi.com/v1", timeout=30, max_retries=3)
+```
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `api_key` | env `GETSOCIALAPI_API_KEY` | your API key |
+| `base_url` | API endpoint | override only for testing |
+| `timeout` | `30` | per-request timeout, seconds |
+| `max_retries` | `3` | retries on 429/503/5xx and network errors |
+
+## Methods
+
+| Method | Route | Description |
+| --- | --- | --- |
+| `profile(user_id)` | `/profile/<id>` | profile by numeric id |
+| `user_info(user_id)` | `/ig/user/info/<id>` | profile by numeric id |
+| `user_by_username(username)` | `/ig/user/username_info/<username>` | profile by username |
+| `user_about(user_id)` | `/user/about/<id>` | About this account: country, joined, former usernames, shared-followers count, verified |
+| `search_username(query, count=10)` | `/search/username/<q>` | search users, resolve username → pk |
+| `similar_users(user_id)` | `/ig/user/similar/<id>` | suggested accounts |
+| `user_medias(user_id, count=12, max_id=None)` | `/ig/user/media/<id>` | profile grid posts |
+| `user_tags(user_id, count=12, max_id=None)` | `/ig/user/tags/<id>` | posts with the user tagged |
+| `user_stories(user_id)` | `/ig/user/stories/<id>` | active stories |
+| `user_highlights(user_id)` | `/ig/user/highlights/<id>` | highlights tray |
+| `highlight_stories(highlight_id)` | `/ig/highlight/stories/<id>` | media of a highlight |
+| `followers(user_id, count=50, max_id=None, query=None)` | `/followers/<id>` | followers list |
+| `following(user_id, count=25, max_id=None, query=None)` | `/following/<id>` | following list |
+| `media_info(media)` | `/ig/media/info/<pk\|shortcode>` | full media card; accepts numeric pk or shortcode |
+| `media_likers(media)` | `/ig/media/likers/<pk\|shortcode>` | users who liked (up to ~100, no pagination) |
+| `media_comments(media, count=None, sort_order="recent", min_id=None)` | `/ig/media/comments/<pk\|shortcode>` | media comments; cursor pagination `next_min_id` → `min_id` |
+| `search_clips(keyword)` | `/ig/media/search_clips/<kw>` | search reels by keyword |
+| `hashtag_info(tag)` | `/ig/hashtag/info/<tag>` | hashtag card |
+| `hashtag_search(query)` | `/ig/hashtag/search/<q>` | search hashtags |
+| `hashtag_posts(tag, max_id=None)` | `/v2/hashtag/posts/<tag>` | posts by hashtag |
+| `location_info(pk)` | `/ig/location/info/<pk>` | location card |
+| `location_media(pk, max_id=None)` | `/ig/location/media/<pk>` | media by location |
+
+Every method returns the raw JSON of the API route as received — nothing is
+unwrapped, filtered or renamed. Where the API supports pagination (`followers`*, `following`, `user_medias`,
+`user_tags`, `hashtag_posts`, `location_media`), pass the cursor from the
+previous response (`next_max_id`) as `max_id`.
+`media_comments` paginates with a different cursor: always request with
+`sort_order="recent"` (the default) and pass `next_min_id` back as `min_id`
+until it comes back null — pages are chronological and disjoint. Instagram
+never returns `next_max_id` for comments, so `max_id` must not be used there.
+*`followers` works on unverified accounts (nearly the full list, plus the
+`query` filter); verified accounts (blue checkmark) expose no more than ~50
+followers — one page, no cursor, `query` ignored. For lists without cursors
+(`search_clips`, `hashtag_search`) each call simply returns the service page.
+
+Full request/response reference with live examples:
+[docs.getsocialapi → API Reference](https://getsocialapi.com/docs/api/instagram/user/get_info_by_id/)
+(see the Documentation section on [getsocialapi.com](https://getsocialapi.com/)).
+
+## Errors
+
+| Exception | HTTP | Notes |
+| --- | --- | --- |
+| `GetSocialAPIError` | — | base class; also network errors |
+| `APIKeyError` | 401 | invalid or missing key |
+| `BadRequestError` | 400 | `.field` points to the bad parameter |
+| `NotFoundError` | 404 | object does not exist — never retried |
+| `RateLimitError` | 429 | `.retry_after` seconds |
+| `ServiceUnavailableError` | 503 | no live accounts, `.retry_after` |
+| `InstagramError` | any | upstream Instagram error, `.status` |
+
+```python
+from getsocialapi_instagram import NotFoundError, RateLimitError
+import time
+
+try:
+    client.instagram.user_info(25025320)
+except NotFoundError:
+    ...  # object does not exist
+except RateLimitError as e:
+    time.sleep(e.retry_after)
+```
+
+Only successful responses (HTTP `200` and `404`) count against your quota.
+Rate limits and plans: [pricing](https://getsocialapi.com/#pricing).
+
+## Support
+
+- Telegram: [@getsocialapi](https://t.me/getsocialapi)
+- Email: [hello@getsocialapi.com](mailto:hello@getsocialapi.com)
+- Website: [getsocialapi.com](https://getsocialapi.com/)
+- Documentation: [getsocialapi.com/docs](https://getsocialapi.com/docs/)
+- Status: [getsocialapi.com/status](https://getsocialapi.com/status/)
+
+## License
+
+MIT

getsocialapi_instagram-0.1.0/README.md

@@ -0,0 +1,164 @@
+# Instagram Scraper API
+
+[![tests](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml/badge.svg)](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)
+
+Python client for the **[GetSocialAPI](https://getsocialapi.com/)** Instagram Scraper API.
+
+- **No cookies required** — you never provide Instagram session cookies
+- **No accounts needed** — zero ban risk for your own profiles
+- Raw Instagram JSON responses, REST endpoints — no transformations
+- Automatic retries with `Retry-After`, typed exceptions
+
+## Installation
+
+```bash
+pip install getsocialapi-instagram
+```
+
+## Migration from `getsocialapi` (git installs)
+
+Before the PyPI release this SDK was installed from git as `getsocialapi`.
+Old imports keep working via a deprecated shim, but please migrate:
+
+```bash
+pip uninstall getsocialapi
+pip install getsocialapi-instagram
+```
+
+```python
+# before
+from getsocialapi import Client
+# after
+from getsocialapi_instagram import Client
+```
+
+## Quickstart
+
+```python
+from getsocialapi_instagram import Client
+
+# Get your API key at https://getsocialapi.com/dashboard/
+client = Client(api_key="gsa_live_...")  # or set GETSOCIALAPI_API_KEY
+
+# Profile by numeric id (or user_by_username for usernames)
+user = client.instagram.user_info(25025320)
+print(user["user"]["follower_count"])
+
+# Posts (grid)
+medias = client.instagram.user_medias(25025320, count=12)
+
+# Followers / following — paginated on unverified accounts: pass `next_max_id`
+# back as `max_id`. Verified accounts (blue checkmark) expose ~50 followers max.
+page = client.instagram.followers(43586162288, count=25)
+page = client.instagram.followers(43586162288, max_id=page["next_max_id"])
+
+# All comments of a post — cursor is next_min_id -> min_id (sort_order="recent" by default)
+comments, cursor = [], None
+while True:
+    page = client.instagram.media_comments(4012386322294878415, count=50, min_id=cursor)
+    comments += page["comments"]
+    cursor = page.get("next_min_id")
+    if not cursor:
+        break
+```
+
+Base URL: `https://api.getsocialapi.com/v1` — authenticate with the API key
+from your [dashboard](https://getsocialapi.com/dashboard/).
+
+## Client
+
+```python
+Client(api_key=None, base_url="https://api.getsocialapi.com/v1", timeout=30, max_retries=3)
+```
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `api_key` | env `GETSOCIALAPI_API_KEY` | your API key |
+| `base_url` | API endpoint | override only for testing |
+| `timeout` | `30` | per-request timeout, seconds |
+| `max_retries` | `3` | retries on 429/503/5xx and network errors |
+
+## Methods
+
+| Method | Route | Description |
+| --- | --- | --- |
+| `profile(user_id)` | `/profile/<id>` | profile by numeric id |
+| `user_info(user_id)` | `/ig/user/info/<id>` | profile by numeric id |
+| `user_by_username(username)` | `/ig/user/username_info/<username>` | profile by username |
+| `user_about(user_id)` | `/user/about/<id>` | About this account: country, joined, former usernames, shared-followers count, verified |
+| `search_username(query, count=10)` | `/search/username/<q>` | search users, resolve username → pk |
+| `similar_users(user_id)` | `/ig/user/similar/<id>` | suggested accounts |
+| `user_medias(user_id, count=12, max_id=None)` | `/ig/user/media/<id>` | profile grid posts |
+| `user_tags(user_id, count=12, max_id=None)` | `/ig/user/tags/<id>` | posts with the user tagged |
+| `user_stories(user_id)` | `/ig/user/stories/<id>` | active stories |
+| `user_highlights(user_id)` | `/ig/user/highlights/<id>` | highlights tray |
+| `highlight_stories(highlight_id)` | `/ig/highlight/stories/<id>` | media of a highlight |
+| `followers(user_id, count=50, max_id=None, query=None)` | `/followers/<id>` | followers list |
+| `following(user_id, count=25, max_id=None, query=None)` | `/following/<id>` | following list |
+| `media_info(media)` | `/ig/media/info/<pk\|shortcode>` | full media card; accepts numeric pk or shortcode |
+| `media_likers(media)` | `/ig/media/likers/<pk\|shortcode>` | users who liked (up to ~100, no pagination) |
+| `media_comments(media, count=None, sort_order="recent", min_id=None)` | `/ig/media/comments/<pk\|shortcode>` | media comments; cursor pagination `next_min_id` → `min_id` |
+| `search_clips(keyword)` | `/ig/media/search_clips/<kw>` | search reels by keyword |
+| `hashtag_info(tag)` | `/ig/hashtag/info/<tag>` | hashtag card |
+| `hashtag_search(query)` | `/ig/hashtag/search/<q>` | search hashtags |
+| `hashtag_posts(tag, max_id=None)` | `/v2/hashtag/posts/<tag>` | posts by hashtag |
+| `location_info(pk)` | `/ig/location/info/<pk>` | location card |
+| `location_media(pk, max_id=None)` | `/ig/location/media/<pk>` | media by location |
+
+Every method returns the raw JSON of the API route as received — nothing is
+unwrapped, filtered or renamed. Where the API supports pagination (`followers`*, `following`, `user_medias`,
+`user_tags`, `hashtag_posts`, `location_media`), pass the cursor from the
+previous response (`next_max_id`) as `max_id`.
+`media_comments` paginates with a different cursor: always request with
+`sort_order="recent"` (the default) and pass `next_min_id` back as `min_id`
+until it comes back null — pages are chronological and disjoint. Instagram
+never returns `next_max_id` for comments, so `max_id` must not be used there.
+*`followers` works on unverified accounts (nearly the full list, plus the
+`query` filter); verified accounts (blue checkmark) expose no more than ~50
+followers — one page, no cursor, `query` ignored. For lists without cursors
+(`search_clips`, `hashtag_search`) each call simply returns the service page.
+
+Full request/response reference with live examples:
+[docs.getsocialapi → API Reference](https://getsocialapi.com/docs/api/instagram/user/get_info_by_id/)
+(see the Documentation section on [getsocialapi.com](https://getsocialapi.com/)).
+
+## Errors
+
+| Exception | HTTP | Notes |
+| --- | --- | --- |
+| `GetSocialAPIError` | — | base class; also network errors |
+| `APIKeyError` | 401 | invalid or missing key |
+| `BadRequestError` | 400 | `.field` points to the bad parameter |
+| `NotFoundError` | 404 | object does not exist — never retried |
+| `RateLimitError` | 429 | `.retry_after` seconds |
+| `ServiceUnavailableError` | 503 | no live accounts, `.retry_after` |
+| `InstagramError` | any | upstream Instagram error, `.status` |
+
+```python
+from getsocialapi_instagram import NotFoundError, RateLimitError
+import time
+
+try:
+    client.instagram.user_info(25025320)
+except NotFoundError:
+    ...  # object does not exist
+except RateLimitError as e:
+    time.sleep(e.retry_after)
+```
+
+Only successful responses (HTTP `200` and `404`) count against your quota.
+Rate limits and plans: [pricing](https://getsocialapi.com/#pricing).
+
+## Support
+
+- Telegram: [@getsocialapi](https://t.me/getsocialapi)
+- Email: [hello@getsocialapi.com](mailto:hello@getsocialapi.com)
+- Website: [getsocialapi.com](https://getsocialapi.com/)
+- Documentation: [getsocialapi.com/docs](https://getsocialapi.com/docs/)
+- Status: [getsocialapi.com/status](https://getsocialapi.com/status/)
+
+## License
+
+MIT

getsocialapi_instagram-0.1.0/getsocialapi_instagram/__init__.py

@@ -0,0 +1,25 @@
+from .client import Client
+from .exceptions import (
+    APIKeyError,
+    BadRequestError,
+    GetSocialAPIError,
+    InstagramError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+from .instagram import InstagramAPI
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Client",
+    "InstagramAPI",
+    "GetSocialAPIError",
+    "BadRequestError",
+    "APIKeyError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "InstagramError",
+]

getsocialapi_instagram-0.1.0/getsocialapi_instagram/client.py

@@ -0,0 +1,31 @@
+import os
+
+from .http import DEFAULT_BASE_URL, Transport
+from .instagram import InstagramAPI
+
+
+class Client:
+    """GetSocialAPI client.
+
+    Usage:
+        from getsocialapi_instagram import Client
+        client = Client(api_key="gsa_live_...")
+        client.instagram.user_by_username("durov")
+    """
+
+    def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, timeout=30,
+                 max_retries=3, session=None):
+        api_key = api_key or os.environ.get("GETSOCIALAPI_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "api_key is required (pass api_key=... or set GETSOCIALAPI_API_KEY)"
+            )
+        self._transport = Transport(
+            base_url=base_url, api_key=api_key, timeout=timeout,
+            max_retries=max_retries, session=session,
+        )
+        self.instagram = InstagramAPI(self._transport)
+
+    def health(self):
+        """Upstream liveness probe: {"ok": true, "state": "ready"}."""
+        return self._transport.request("GET", "/health", auth=False)

getsocialapi_instagram-0.1.0/getsocialapi_instagram/exceptions.py

@@ -0,0 +1,80 @@
+class GetSocialAPIError(Exception):
+    """Base error for all GetSocialAPI SDK failures."""
+
+    def __init__(self, message, response=None, body=None):
+        super().__init__(message)
+        self.response = response
+        self.body = body if body is not None else {}
+
+
+def _reason(body, fallback):
+    """Extract a human-readable reason: {"error": "..."} | {"error": {"message"}} | {"message": ..."}."""
+    err = body.get("error")
+    if isinstance(err, dict):
+        err = err.get("message")
+    if isinstance(err, str) and err:
+        return err
+    msg = body.get("message")
+    if isinstance(msg, str) and msg:
+        return msg
+    return fallback
+
+
+class BadRequestError(GetSocialAPIError):
+    """400 — invalid parameters (body: {"error", "field"})."""
+
+    def __init__(self, response=None, body=None):
+        body = body or {}
+        field = body.get("field")
+        msg = _reason(body, "Bad request")
+        if field:
+            msg = f"{msg} (field: {field})"
+        super().__init__(msg, response, body)
+        self.field = field
+
+
+class UnauthorizedError(GetSocialAPIError):
+    """401 — invalid or missing API key."""
+
+    def __init__(self, response=None, body=None):
+        super().__init__("Invalid API key", response, body)
+
+
+class NotFoundError(GetSocialAPIError):
+    """404 — target object does not exist. Do not retry."""
+
+    def __init__(self, response=None, body=None):
+        body = body or {}
+        msg = _reason(body, "Not found")
+        super().__init__(msg, response, body)
+
+
+class RateLimitError(GetSocialAPIError):
+    """429 — key rate limit exceeded. Honors Retry-After."""
+
+    def __init__(self, response=None, body=None, retry_after=1):
+        super().__init__(f"Rate limit exceeded, retry after {retry_after}s", response, body)
+        self.retry_after = retry_after
+
+
+class ServiceUnavailableError(GetSocialAPIError):
+    """503 — no live accounts or the service is stopped."""
+
+    def __init__(self, response=None, body=None, retry_after=None):
+        msg = "Service unavailable"
+        if retry_after:
+            msg += f", retry after {retry_after}s"
+        super().__init__(msg, response, body)
+        self.retry_after = retry_after
+
+
+class InstagramError(GetSocialAPIError):
+    """Non-404 error returned by the Instagram private API (raw mode)."""
+
+    def __init__(self, status, message, response=None, body=None):
+        super().__init__(f"Instagram API error {status}: {message}", response, body)
+        self.status = status
+
+
+# Convenience alias
+APIKeyError = UnauthorizedError

getsocialapi_instagram-0.1.0/getsocialapi_instagram/http.py

@@ -0,0 +1,82 @@
+import time
+
+import requests
+
+from .exceptions import (
+    BadRequestError,
+    GetSocialAPIError,
+    InstagramError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnauthorizedError,
+)
+
+DEFAULT_BASE_URL = "https://api.getsocialapi.com/v1"
+
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class Transport:
+    """HTTP transport: auth, JSON parsing, retries with Retry-After."""
+
+    def __init__(self, base_url=DEFAULT_BASE_URL, api_key=None, timeout=30,
+                 max_retries=3, session=None):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+
+    def request(self, method, path, params=None, auth=True):
+        url = f"{self.base_url}{path}"
+        headers = {"X-API-Key": self.api_key} if auth else {}
+        attempts = self.max_retries + 1
+        last_exc = None
+        for attempt in range(attempts):
+            try:
+                resp = self.session.request(
+                    method, url, params=params, headers=headers, timeout=self.timeout,
+                )
+            except (requests.ConnectionError, requests.Timeout) as e:
+                last_exc = e
+                if attempt < attempts - 1:
+                    time.sleep(min(2 ** attempt, 10))
+                    continue
+                raise GetSocialAPIError(f"Network error: {e}") from e
+
+            if resp.status_code in RETRYABLE_STATUS and attempt < attempts - 1:
+                time.sleep(self._retry_after(resp))
+                continue
+            return self._parse(resp)
+        raise GetSocialAPIError("Request failed after retries")  # pragma: no cover
+
+    @staticmethod
+    def _retry_after(resp):
+        try:
+            return min(max(int(float(resp.headers.get("Retry-After", 1))), 0), 30)
+        except (TypeError, ValueError):
+            return 1
+
+    def _parse(self, resp):
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {"raw": resp.text}
+
+        if resp.status_code == 401:
+            raise UnauthorizedError(resp, body)
+        if resp.status_code == 400:
+            raise BadRequestError(resp, body)
+        if resp.status_code == 404:
+            raise NotFoundError(resp, body)
+        if resp.status_code == 429:
+            raise RateLimitError(resp, body, retry_after=self._retry_after(resp))
+        if resp.status_code == 503:
+            raise ServiceUnavailableError(resp, body, retry_after=self._retry_after(resp))
+        if resp.status_code >= 400:
+            # Instagram errors in raw mode: {"message": "...", "status": "fail"}
+            if isinstance(body, dict) and body.get("status") == "fail":
+                raise InstagramError(resp.status_code, body.get("message", "unknown"), resp, body)
+            raise GetSocialAPIError(f"HTTP {resp.status_code}: {body}", resp, body)
+        return body

getsocialapi_instagram-0.1.0/getsocialapi_instagram/instagram.py

@@ -0,0 +1,257 @@
+from urllib.parse import quote
+import re
+
+
+def _quote(value):
+    return quote(str(value), safe="")
+
+
+def _media_arg(value, name="media id"):
+    """Numeric media pk or shortcode (e.g. DehVsgBi3sH)."""
+    s = str(value)
+    if s.isdigit():
+        return _digits(s, name)
+    if re.fullmatch(r"[A-Za-z0-9_-]{5,64}", s):
+        return s
+    raise ValueError(f"{name} must be a numeric pk or a shortcode, "
+                     f"got: {value!r}")
+
+
+def _digits(value, name, max_len=20):
+    s = str(value)
+    if not s.isdigit() or not 1 <= len(s) <= max_len:
+        raise ValueError(f"{name} must be 1-{max_len} digits, got: {value!r}")
+    return s
+
+
+def _length(value, name, lo, hi):
+    s = str(value)
+    if not lo <= len(s) <= hi:
+        raise ValueError(f"{name} must be {lo}-{hi} characters, got: {value!r}")
+    return s
+
+
+def _tag(value):
+    return _quote(_length(str(value).lstrip("#"), "tag", 1, 64))
+
+
+def _count(value, lo=1, hi=50, default=None):
+    if value is None:
+        return default
+    if isinstance(value, bool) or not isinstance(value, int) or not lo <= value <= hi:
+        raise ValueError(f"count must be an integer {lo}-{hi}, got: {value!r}")
+    return value
+
+
+class InstagramAPI:
+    """Instagram endpoints of GetSocialAPI.
+
+    Methods map 1:1 to API routes and return the raw JSON responses as received.
+    """
+
+    def __init__(self, transport):
+        self._t = transport
+
+    # ---------- Profile ----------
+
+    def user_info(self, user_id):
+        """GET /ig/user/info/{user_id} — profile by numeric id."""
+        return self._t.request("GET", f"/ig/user/info/{_digits(user_id, 'user_id')}")
+
+    def user_by_username(self, username):
+        """GET /ig/user/username_info/{username} — profile by username."""
+        return self._t.request("GET", f"/ig/user/username_info/{_length(username, 'username', 1, 64)}")
+
+    def profile(self, user_id):
+        """GET /profile/{user_id} — profile by numeric id."""
+        return self._t.request("GET", f"/profile/{_digits(user_id, 'user_id')}")
+
+    def user_about(self, user_id):
+        """GET /user/about/{user_id} — About this account.
+
+        The "About this account" screen: country, registration month,
+        former usernames count, accounts-with-shared-followers count,
+        verification. Sparse accounts return null fields — check
+        `has_about_data` / `unavailable` before using them.
+        """
+        return self._t.request("GET", f"/user/about/{_digits(user_id, 'user_id')}")
+
+    def search_username(self, query, count=10):
+        """GET /search/username/{query} — search users.
+
+        `count` is forwarded to the service, but the response may include
+        one extra exact-match entry beyond it.
+        """
+        return self._t.request("GET", f"/search/username/{_quote(query)}",
+                               params={"count": _count(count, default=10)})
+
+    def similar_users(self, user_id):
+        """GET /ig/user/similar/{user_id} — suggested accounts."""
+        return self._t.request("GET", f"/ig/user/similar/{_digits(user_id, 'user_id')}")
+
+    # ---------- User content ----------
+
+    def user_medias(self, user_id, count=12, max_id=None):
+        """GET /ig/user/media/{user_id} — profile grid posts."""
+        return self._t.request("GET", f"/ig/user/media/{_digits(user_id, 'user_id')}",
+                               params=_page(count, max_id, default=12))
+
+    def user_tags(self, user_id, count=12, max_id=None):
+        """GET /ig/user/tags/{user_id} — posts where the user is tagged."""
+        return self._t.request("GET", f"/ig/user/tags/{_digits(user_id, 'user_id')}",
+                               params=_page(count, max_id, default=12))
+
+    def user_stories(self, user_id):
+        """GET /ig/user/stories/{user_id} — active stories."""
+        return self._t.request("GET", f"/ig/user/stories/{_digits(user_id, 'user_id')}")
+
+    def user_highlights(self, user_id):
+        """GET /ig/user/highlights/{user_id} — highlights tray."""
+        return self._t.request("GET", f"/ig/user/highlights/{_digits(user_id, 'user_id')}")
+
+    def highlight_stories(self, highlight_id):
+        """GET /ig/highlight/stories/{highlight_id} — media of a highlight.
+
+        Accepts the tray id as is — the leading `highlight:` prefix
+        (as returned by `user_highlights`) is trimmed automatically.
+        """
+        hid = str(highlight_id)
+        if hid.startswith("highlight:"):
+            hid = hid[len("highlight:"):]
+        return self._t.request("GET", f"/ig/highlight/stories/{_quote(_length(hid, 'highlight_id', 1, 64))}")
+
+    # ---------- Followers / following ----------
+
+    def followers(self, user_id, count=50, max_id=None, query=None):
+        """GET /followers/{user_id} — followers list.
+
+        On unverified accounts `count`, the `next_max_id` cursor and the
+        `query` filter work — nearly the full list is accessible and
+        searchable. On verified accounts (blue checkmark) Instagram exposes
+        no more than ~50 followers: one page, no cursor, `query` ignored.
+        """
+        params = _page(count, max_id, default=50)
+        if query is not None:
+            params["query"] = query
+        return self._t.request("GET", f"/followers/{_digits(user_id, 'user_id')}",
+                               params=params)
+
+    def following(self, user_id, count=25, max_id=None, query=None):
+        """GET /following/{user_id} — following list.
+
+        Page size: the service returns the default 25 accounts per page and
+        at most 25 (values above 50 are rejected). The response carries
+        `next_max_id` — pass it as `max_id` for the next page. `query`
+        filters the list by name.
+        """
+        params = _page(count, max_id, default=25, hi=50)
+        if query is not None:
+            params["query"] = query
+        return self._t.request("GET", f"/following/{_digits(user_id, 'user_id')}",
+                               params=params)
+
+    # ---------- Media ----------
+
+    def media_info(self, media):
+        """GET /ig/media/info/{pk|shortcode} — full media card.
+
+        Accepts a numeric pk or a post shortcode (e.g. "Deu3BoCBbDP"):
+        items[0] carries pk, code, media_type (1=photo, 2=video,
+        8=carousel), caption, like/comment/view counts, taken_at, owner.
+        """
+        return self._t.request("GET", f"/ig/media/info/{_media_arg(media)}")
+
+    def media_likers(self, media):
+        """GET /ig/media/likers/{pk|shortcode} — users who liked the media.
+
+        One shot of up to ~100 users; the route has no pagination.
+        """
+        return self._t.request("GET", f"/ig/media/likers/{_media_arg(media)}")
+
+    def media_comments(self, media, count=None, sort_order="recent", min_id=None):
+        """GET /ig/media/comments/{pk|shortcode} — media comments.
+
+        Accepts a numeric pk or a post shortcode (e.g. "Deu3BoCBbDP").
+
+        Full pagination works only with `sort_order="recent"` (default):
+        pages are strictly chronological (newer → older) and disjoint.
+        The cursor is `next_min_id` from the previous response — pass it
+        back as `min_id` verbatim (it is a JSON string with special
+        characters; the transport URL-encodes it). Collect until
+        `next_min_id` is null/empty or `comments` is an empty list.
+
+        Instagram never returns `next_max_id` for this route — `max_id`
+        pagination must not be used. `count` (1-50) is accepted by the
+        validator but the real page size is ~12-20 comments. Without
+        `sort_order` (ranked) the service returns a ~15 comment preview
+        whose pages overlap between pool accounts.
+        """
+        params = {}
+        if count is not None:
+            params["count"] = _count(count)
+        if sort_order is not None:
+            if sort_order not in ("recent", "ranked"):
+                raise ValueError('sort_order must be "recent" or "ranked", '
+                                 f"got: {sort_order!r}")
+            params["sort_order"] = sort_order
+        if min_id is not None:
+            params["min_id"] = min_id
+        return self._t.request("GET", f"/ig/media/comments/{_media_arg(media)}",
+                               params=params)
+
+    def search_clips(self, keyword):
+        """GET /ig/media/search_clips/{keyword} — search reels by keyword.
+
+        The service returns its native page (~12 clips); a page-size
+        parameter is not supported by the API for this route.
+        """
+        kw = _length(keyword, "keyword", 1, 100)
+        return self._t.request("GET", f"/ig/media/search_clips/{_quote(kw)}")
+
+    # ---------- Hashtags ----------
+
+    def hashtag_info(self, tag):
+        """GET /ig/hashtag/info/{tag} — hashtag card. A leading # is trimmed."""
+        return self._t.request("GET", f"/ig/hashtag/info/{_tag(tag)}")
+
+    def hashtag_search(self, query):
+        """GET /ig/hashtag/search/{query} — search hashtags.
+
+        Returns the full first page of tag matches; a page-size
+        parameter is not supported by the API for this route.
+        """
+        return self._t.request("GET", f"/ig/hashtag/search/{_quote(query)}")
+
+    def hashtag_posts(self, tag, max_id=None):
+        """GET /v2/hashtag/posts/{tag} — posts by hashtag. A leading # is trimmed.
+
+        The service returns its native page (~15-18 posts) plus `next_max_id`
+        for pagination via `max_id`; a page-size parameter is not supported.
+        """
+        params = {"max_id": max_id} if max_id is not None else None
+        return self._t.request("GET", f"/v2/hashtag/posts/{_tag(tag)}",
+                               params=params)
+
+    # ---------- Locations ----------
+
+    def location_info(self, pk):
+        """GET /ig/location/info/{pk} — location card."""
+        return self._t.request("GET", f"/ig/location/info/{_digits(pk, 'pk')}")
+
+    def location_media(self, pk, max_id=None):
+        """GET /ig/location/media/{pk} — media by location.
+
+        The service returns its native page; pass `next_max_id` from a
+        previous response as `max_id` to request the next page. The
+        response also carries `next_page` — a page counter, not a cursor.
+        """
+        params = {"max_id": max_id} if max_id is not None else None
+        return self._t.request("GET", f"/ig/location/media/{_digits(pk, 'pk')}",
+                               params=params)
+
+
+def _page(count, max_id, default=12, hi=50):
+    params = {"count": _count(count, default=default, hi=hi)}
+    if max_id is not None:
+        params["max_id"] = max_id
+    return params

getsocialapi_instagram-0.1.0/getsocialapi_instagram.egg-info/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: getsocialapi-instagram
+Version: 0.1.0
+Summary: GetSocialAPI — client library for the Instagram API (no cookies, no accounts required)
+Author: GetSocialAPI
+License: MIT
+Project-URL: Homepage, https://getsocialapi.com
+Project-URL: Documentation, https://getsocialapi.com/docs/
+Keywords: instagram,api,scraping,sdk,getsocialapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Dynamic: license-file
+
+# Instagram Scraper API
+
+[![tests](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml/badge.svg)](https://github.com/GetSocialAPI/Instagram-Scraper-API/actions/workflows/tests.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)
+
+Python client for the **[GetSocialAPI](https://getsocialapi.com/)** Instagram Scraper API.
+
+- **No cookies required** — you never provide Instagram session cookies
+- **No accounts needed** — zero ban risk for your own profiles
+- Raw Instagram JSON responses, REST endpoints — no transformations
+- Automatic retries with `Retry-After`, typed exceptions
+
+## Installation
+
+```bash
+pip install getsocialapi-instagram
+```
+
+## Migration from `getsocialapi` (git installs)
+
+Before the PyPI release this SDK was installed from git as `getsocialapi`.
+Old imports keep working via a deprecated shim, but please migrate:
+
+```bash
+pip uninstall getsocialapi
+pip install getsocialapi-instagram
+```
+
+```python
+# before
+from getsocialapi import Client
+# after
+from getsocialapi_instagram import Client
+```
+
+## Quickstart
+
+```python
+from getsocialapi_instagram import Client
+
+# Get your API key at https://getsocialapi.com/dashboard/
+client = Client(api_key="gsa_live_...")  # or set GETSOCIALAPI_API_KEY
+
+# Profile by numeric id (or user_by_username for usernames)
+user = client.instagram.user_info(25025320)
+print(user["user"]["follower_count"])
+
+# Posts (grid)
+medias = client.instagram.user_medias(25025320, count=12)
+
+# Followers / following — paginated on unverified accounts: pass `next_max_id`
+# back as `max_id`. Verified accounts (blue checkmark) expose ~50 followers max.
+page = client.instagram.followers(43586162288, count=25)
+page = client.instagram.followers(43586162288, max_id=page["next_max_id"])
+
+# All comments of a post — cursor is next_min_id -> min_id (sort_order="recent" by default)
+comments, cursor = [], None
+while True:
+    page = client.instagram.media_comments(4012386322294878415, count=50, min_id=cursor)
+    comments += page["comments"]
+    cursor = page.get("next_min_id")
+    if not cursor:
+        break
+```
+
+Base URL: `https://api.getsocialapi.com/v1` — authenticate with the API key
+from your [dashboard](https://getsocialapi.com/dashboard/).
+
+## Client
+
+```python
+Client(api_key=None, base_url="https://api.getsocialapi.com/v1", timeout=30, max_retries=3)
+```
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `api_key` | env `GETSOCIALAPI_API_KEY` | your API key |
+| `base_url` | API endpoint | override only for testing |
+| `timeout` | `30` | per-request timeout, seconds |
+| `max_retries` | `3` | retries on 429/503/5xx and network errors |
+
+## Methods
+
+| Method | Route | Description |
+| --- | --- | --- |
+| `profile(user_id)` | `/profile/<id>` | profile by numeric id |
+| `user_info(user_id)` | `/ig/user/info/<id>` | profile by numeric id |
+| `user_by_username(username)` | `/ig/user/username_info/<username>` | profile by username |
+| `user_about(user_id)` | `/user/about/<id>` | About this account: country, joined, former usernames, shared-followers count, verified |
+| `search_username(query, count=10)` | `/search/username/<q>` | search users, resolve username → pk |
+| `similar_users(user_id)` | `/ig/user/similar/<id>` | suggested accounts |
+| `user_medias(user_id, count=12, max_id=None)` | `/ig/user/media/<id>` | profile grid posts |
+| `user_tags(user_id, count=12, max_id=None)` | `/ig/user/tags/<id>` | posts with the user tagged |
+| `user_stories(user_id)` | `/ig/user/stories/<id>` | active stories |
+| `user_highlights(user_id)` | `/ig/user/highlights/<id>` | highlights tray |
+| `highlight_stories(highlight_id)` | `/ig/highlight/stories/<id>` | media of a highlight |
+| `followers(user_id, count=50, max_id=None, query=None)` | `/followers/<id>` | followers list |
+| `following(user_id, count=25, max_id=None, query=None)` | `/following/<id>` | following list |
+| `media_info(media)` | `/ig/media/info/<pk\|shortcode>` | full media card; accepts numeric pk or shortcode |
+| `media_likers(media)` | `/ig/media/likers/<pk\|shortcode>` | users who liked (up to ~100, no pagination) |
+| `media_comments(media, count=None, sort_order="recent", min_id=None)` | `/ig/media/comments/<pk\|shortcode>` | media comments; cursor pagination `next_min_id` → `min_id` |
+| `search_clips(keyword)` | `/ig/media/search_clips/<kw>` | search reels by keyword |
+| `hashtag_info(tag)` | `/ig/hashtag/info/<tag>` | hashtag card |
+| `hashtag_search(query)` | `/ig/hashtag/search/<q>` | search hashtags |
+| `hashtag_posts(tag, max_id=None)` | `/v2/hashtag/posts/<tag>` | posts by hashtag |
+| `location_info(pk)` | `/ig/location/info/<pk>` | location card |
+| `location_media(pk, max_id=None)` | `/ig/location/media/<pk>` | media by location |
+
+Every method returns the raw JSON of the API route as received — nothing is
+unwrapped, filtered or renamed. Where the API supports pagination (`followers`*, `following`, `user_medias`,
+`user_tags`, `hashtag_posts`, `location_media`), pass the cursor from the
+previous response (`next_max_id`) as `max_id`.
+`media_comments` paginates with a different cursor: always request with
+`sort_order="recent"` (the default) and pass `next_min_id` back as `min_id`
+until it comes back null — pages are chronological and disjoint. Instagram
+never returns `next_max_id` for comments, so `max_id` must not be used there.
+*`followers` works on unverified accounts (nearly the full list, plus the
+`query` filter); verified accounts (blue checkmark) expose no more than ~50
+followers — one page, no cursor, `query` ignored. For lists without cursors
+(`search_clips`, `hashtag_search`) each call simply returns the service page.
+
+Full request/response reference with live examples:
+[docs.getsocialapi → API Reference](https://getsocialapi.com/docs/api/instagram/user/get_info_by_id/)
+(see the Documentation section on [getsocialapi.com](https://getsocialapi.com/)).
+
+## Errors
+
+| Exception | HTTP | Notes |
+| --- | --- | --- |
+| `GetSocialAPIError` | — | base class; also network errors |
+| `APIKeyError` | 401 | invalid or missing key |
+| `BadRequestError` | 400 | `.field` points to the bad parameter |
+| `NotFoundError` | 404 | object does not exist — never retried |
+| `RateLimitError` | 429 | `.retry_after` seconds |
+| `ServiceUnavailableError` | 503 | no live accounts, `.retry_after` |
+| `InstagramError` | any | upstream Instagram error, `.status` |
+
+```python
+from getsocialapi_instagram import NotFoundError, RateLimitError
+import time
+
+try:
+    client.instagram.user_info(25025320)
+except NotFoundError:
+    ...  # object does not exist
+except RateLimitError as e:
+    time.sleep(e.retry_after)
+```
+
+Only successful responses (HTTP `200` and `404`) count against your quota.
+Rate limits and plans: [pricing](https://getsocialapi.com/#pricing).
+
+## Support
+
+- Telegram: [@getsocialapi](https://t.me/getsocialapi)
+- Email: [hello@getsocialapi.com](mailto:hello@getsocialapi.com)
+- Website: [getsocialapi.com](https://getsocialapi.com/)
+- Documentation: [getsocialapi.com/docs](https://getsocialapi.com/docs/)
+- Status: [getsocialapi.com/status](https://getsocialapi.com/status/)
+
+## License
+
+MIT

getsocialapi_instagram-0.1.0/getsocialapi_instagram.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+getsocialapi_instagram/__init__.py
+getsocialapi_instagram/client.py
+getsocialapi_instagram/exceptions.py
+getsocialapi_instagram/http.py
+getsocialapi_instagram/instagram.py
+getsocialapi_instagram.egg-info/PKG-INFO
+getsocialapi_instagram.egg-info/SOURCES.txt
+getsocialapi_instagram.egg-info/dependency_links.txt
+getsocialapi_instagram.egg-info/requires.txt
+getsocialapi_instagram.egg-info/top_level.txt
+tests/test_sdk.py

getsocialapi_instagram-0.1.0/getsocialapi_instagram.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

getsocialapi_instagram-0.1.0/getsocialapi_instagram.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.25

getsocialapi_instagram-0.1.0/getsocialapi_instagram.egg-info/top_level.txt

@@ -0,0 +1 @@
+getsocialapi_instagram

getsocialapi_instagram-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "getsocialapi-instagram"
+version = "0.1.0"
+description = "GetSocialAPI — client library for the Instagram API (no cookies, no accounts required)"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "GetSocialAPI" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.25"]
+keywords = ["instagram", "api", "scraping", "sdk", "getsocialapi"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://getsocialapi.com"
+Documentation = "https://getsocialapi.com/docs/"
+
+[tool.setuptools.packages.find]
+include = ["getsocialapi_instagram*"]

getsocialapi_instagram-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

getsocialapi_instagram-0.1.0/tests/test_sdk.py

@@ -0,0 +1,229 @@
+import json
+import os
+import sys
+import unittest
+from unittest.mock import MagicMock
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from getsocialapi_instagram import Client, InstagramAPI  # noqa: E402
+from getsocialapi_instagram.exceptions import (  # noqa: E402
+    APIKeyError,
+    BadRequestError,
+    InstagramError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+from getsocialapi_instagram.http import Transport  # noqa: E402
+
+
+def fake_response(status, body=None, headers=None):
+    r = MagicMock()
+    r.status_code = status
+    r.headers = headers or {}
+    r.text = json.dumps(body) if body is not None else ""
+    r.json = (lambda b=body: b) if body is not None else (lambda: (_ for _ in ()).throw(ValueError()))
+    return r
+
+
+def make_client(session):
+    return Client(api_key="test_key", session=session, max_retries=0)
+
+
+class TestClient(unittest.TestCase):
+    def test_requires_key(self):
+        with self.assertRaises(ValueError):
+            Client(api_key=None)
+
+    def test_health_no_auth_header(self):
+        s = MagicMock()
+        s.request.return_value = fake_response(200, {"ok": True, "state": "ready"})
+        c = make_client(s)
+        self.assertEqual(c.health(), {"ok": True, "state": "ready"})
+        kwargs = s.request.call_args.kwargs
+        self.assertEqual(kwargs["headers"], {})
+
+
+class TestErrors(unittest.TestCase):
+    def _transport(self, resp):
+        t = Transport(api_key="k", max_retries=0)
+        t.session = MagicMock()
+        t.session.request.return_value = resp
+        return t
+
+    def test_401(self):
+        with self.assertRaises(APIKeyError):
+            self._transport(fake_response(401, {"error": "bad key"})).request("GET", "/x")
+
+    def test_400_message_field(self):
+        from getsocialapi_instagram.exceptions import BadRequestError, NotFoundError
+        e = BadRequestError(body={"message": "Location does not exist.", "status": "fail"})
+        self.assertEqual(str(e), "Location does not exist.")
+        n = NotFoundError(body={"message": "Location does not exist.", "status": "fail"})
+        self.assertEqual(str(n), "Location does not exist.")
+        g = NotFoundError(body={"error": {"code": 404, "message": "Unknown endpoint"}})
+        self.assertEqual(str(g), "Unknown endpoint")
+
+    def test_400_field(self):
+        with self.assertRaises(BadRequestError) as ctx:
+            self._transport(fake_response(400, {"error": "invalid id", "field": "user_id"})).request("GET", "/x")
+        self.assertEqual(ctx.exception.field, "user_id")
+
+    def test_404_not_found(self):
+        with self.assertRaises(NotFoundError):
+            self._transport(fake_response(404, {"message": "user does not exist", "status": "fail"})).request("GET", "/x")
+
+    def test_429_retry_after(self):
+        with self.assertRaises(RateLimitError) as ctx:
+            self._transport(fake_response(429, {}, {"Retry-After": "7"})).request("GET", "/x")
+        self.assertEqual(ctx.exception.retry_after, 7)
+
+    def test_503(self):
+        with self.assertRaises(ServiceUnavailableError):
+            self._transport(fake_response(503, {})).request("GET", "/x")
+
+    def test_ig_error(self):
+        with self.assertRaises(InstagramError):
+            self._transport(fake_response(500, {"message": "oops", "status": "fail"})).request("GET", "/x")
+
+
+class TestInstagramAPI(unittest.TestCase):
+    def api(self):
+        t = MagicMock()
+        return InstagramAPI(t), t
+
+    def check(self, method, args, expected_path, expected_params=None, kwargs=None):
+        a, t = self.api()
+        getattr(a, method)(*args, **(kwargs or {}))
+        call = t.request.call_args
+        self.assertEqual(call.args, ("GET", expected_path))
+        if expected_params is not None:
+            self.assertEqual(call.kwargs.get("params"), expected_params)
+
+    def test_profile(self):
+        self.check("profile", ("25025320",), "/profile/25025320")
+
+    def test_user_info(self):
+        self.check("user_info", (25025320,), "/ig/user/info/25025320")
+
+    def test_user_about(self):
+        self.check("user_about", (25025320,), "/user/about/25025320")
+
+    def test_hashtag_info_trims_hash(self):
+        self.check("hashtag_info", ("#gymgirl",), "/ig/hashtag/info/gymgirl")
+
+    def test_hashtag_posts_trims_hash(self):
+        self.check("hashtag_posts", ("#gymgirl",), "/v2/hashtag/posts/gymgirl")
+        self.check("hashtag_posts", ("##gym girl",), "/v2/hashtag/posts/gym%20girl")
+
+    def test_username_info(self):
+        self.check("user_by_username", ("instagram",), "/ig/user/username_info/instagram")
+
+    def test_search_username(self):
+        self.check("search_username", ("du",), "/search/username/du", {"count": 10})
+
+    def test_user_medias(self):
+        self.check("user_medias", (25025320,), "/ig/user/media/25025320", {"count": 12})
+
+    def test_user_medias_max_id(self):
+        self.check("user_medias", (25025320,), "/ig/user/media/25025320",
+                   {"count": 50, "max_id": "CUR"}, {"count": 50, "max_id": "CUR"})
+
+    def test_followers_default(self):
+        self.check("followers", (25025320,), "/followers/25025320", {"count": 50})
+
+    def test_followers_page_and_filter(self):
+        self.check("followers", (25025320,), "/followers/25025320",
+                   {"count": 25, "max_id": "CUR", "query": "an"},
+                   {"count": 25, "max_id": "CUR", "query": "an"})
+
+    def test_following_default(self):
+        self.check("following", (25025320,), "/following/25025320", {"count": 25})
+
+    def test_following_page_and_filter(self):
+        self.check("following", (25025320,), "/following/25025320",
+                   {"count": 25, "max_id": "CUR", "query": "bo"},
+                   {"count": 25, "max_id": "CUR", "query": "bo"})
+
+    def test_media_comments_default(self):
+        self.check("media_comments", (3141085633626004499,),
+                   "/ig/media/comments/3141085633626004499",
+                   {"sort_order": "recent"})
+
+    def test_media_shortcode_args(self):
+        self.check("media_info", ("Deu3BoCBbDP",), "/ig/media/info/Deu3BoCBbDP")
+        self.check("media_likers", ("DehVsgBi3sH",), "/ig/media/likers/DehVsgBi3sH")
+        self.check("media_comments", ("Deu3BoCBbDP",),
+                   "/ig/media/comments/Deu3BoCBbDP",
+                   {"sort_order": "recent"})
+
+    def test_media_bad_arg(self):
+        a, _ = self.api()
+        for bad in ("", "abc!", "#tag", "way too long to be a shortcode at all"):
+            with self.assertRaises(ValueError):
+                a.media_info(bad)
+
+    def test_media_comments_page(self):
+        cur = '{"cached_comments_cursor":"123","bifilter_token":"abc+/=|"}'
+        self.check("media_comments", (3141085633626004499,),
+                   "/ig/media/comments/3141085633626004499",
+                   {"count": 50, "sort_order": "recent", "min_id": cur},
+                   {"count": 50, "min_id": cur})
+
+    def test_media_comments_ranked(self):
+        self.check("media_comments", (3141085633626004499,),
+                   "/ig/media/comments/3141085633626004499",
+                   {"sort_order": "ranked"}, {"sort_order": "ranked"})
+
+    def test_media_comments_bad_sort_order(self):
+        a, _ = self.api()
+        with self.assertRaises(ValueError):
+            a.media_comments(3141085633626004499, sort_order="top")
+
+    def test_media_comments_bad_count(self):
+        a, _ = self.api()
+        with self.assertRaises(ValueError):
+            a.media_comments(3141085633626004499, count=51)
+
+    def test_hashtag_posts_default(self):
+        self.check("hashtag_posts", ("gymgirl",), "/v2/hashtag/posts/gymgirl")
+
+    def test_hashtag_posts_max_id(self):
+        self.check("hashtag_posts", ("gymgirl",), "/v2/hashtag/posts/gymgirl",
+                   {"max_id": "CUR"}, {"max_id": "CUR"})
+
+    def test_location_media(self):
+        self.check("location_media", (213069402,), "/ig/location/media/213069402")
+
+    def test_location_media_max_id(self):
+        self.check("location_media", (213069402,), "/ig/location/media/213069402",
+                   {"max_id": "NEXT"}, {"max_id": "NEXT"})
+
+    def test_search_clips(self):
+        self.check("search_clips", ("hello world",), "/ig/media/search_clips/hello%20world")
+
+    def test_hashtag_search_no_count(self):
+        self.check("hashtag_search", ("gym girl",), "/ig/hashtag/search/gym%20girl")
+
+    def test_highlight_stories_trims_prefix(self):
+        self.check("highlight_stories", ("highlight:18223279177302854",),
+                   "/ig/highlight/stories/18223279177302854")
+        self.check("highlight_stories", ("18223279177302854",),
+                   "/ig/highlight/stories/18223279177302854")
+
+    def test_validations(self):
+        a, _ = self.api()
+        for fn, bad in [
+            (a.user_info, "12x"),
+            (a.user_by_username, ""),
+            (a.user_medias, 0),
+        ]:
+            with self.assertRaises(ValueError):
+                fn(bad) if fn not in (a.user_medias,) else fn(1, count=0)
+        with self.assertRaises(ValueError):
+            a.search_clips("")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)