apple-app-store-scraper-lite 0.1.0__tar.gz

apple_app_store_scraper_lite-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Agents Kit
+
+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.

apple_app_store_scraper_lite-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: apple-app-store-scraper-lite
+Version: 0.1.0
+Summary: A lightweight, pure-Python library for scraping Apple App Store data via iTunes API
+Author: Apple App Store Scraper Lite Contributors
+License: MIT
+Project-URL: Homepage, https://apify.com/Redbaron/apple-app-store-scraper-lite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# Apple App Store Scraper Lite
+
+> **Run it hosted, no setup:** [Apple App Store Scraper Lite on Apify](https://apify.com/Redbaron/apple-app-store-scraper-lite) — pay per result, nothing to install or maintain.
+
+A lightweight, pure-Python library for scraping Apple App Store data via the iTunes API. Supports searching for apps, getting app details, extracting reviews, and discovering top charts — all without a browser, using only standard library HTTP requests.
+
+## Features
+
+- **Search apps** by keyword with full metadata (name, developer, price, rating, description, screenshots, supported devices)
+- **Get app details** by App Store ID or URL
+- **Extract reviews** with ratings, titles, content, author, date, and app version
+- **Discover top charts** (free, paid, grossing, new releases) by country
+- **Pure Python** — no external dependencies, no browser automation
+- **Pagination support** — automatically follows next-page links
+- **Privacy-safe** — never returns personal data (emails, phones, usernames beyond public review author names)
+
+## Installation
+
+```bash
+pip install apple-app-store-scraper-lite-0.1.0-py3-none-any.whl
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from apple_app_store_scraper_lite import start_urls, process, next_urls
+import urllib.request
+import json
+
+# 1. Build start URLs from your parameters
+params = {
+    "mode": "search",
+    "searchTerm": "photo editor",
+    "country": "us"
+}
+urls = start_urls(params)
+print(f"Fetching: {urls[0]}")
+
+# 2. Fetch the response (using stdlib urllib)
+with urllib.request.urlopen(urls[0]) as response:
+    text = response.read().decode("utf-8")
+
+# 3. Parse into structured records
+records = process(text, urls[0])
+print(f"Found {len(records)} apps")
+for app in records[:3]:
+    print(f"  - {app['appName']} ({app['appId']}) by {app['developer']} — {app['price']['formatted']} — ⭐ {app['rating']['value']}")
+
+# 4. Follow pagination if needed
+for next_url in next_urls(text, urls[0]):
+    with urllib.request.urlopen(next_url) as response:
+        more_text = response.read().decode("utf-8")
+    more_records = process(more_text, next_url)
+    print(f"Next page: {len(more_records)} more apps")
+```
+
+## Modes
+
+| Mode | Description | Required Params | Optional Params |
+|------|-------------|-----------------|-----------------|
+| `search` | Search apps by keyword | `mode`, `searchTerm` | `country` (default: `us`) |
+| `details` | Get full app metadata | `mode`, `appIds` | `country` (default: `us`) |
+| `reviews` | Extract user reviews | `mode`, `appIds` | `country` (default: `us`) |
+| `charts` | Top charts by category | `mode` | `chartType` (default: `top-free`), `country` (default: `us`) |
+
+### Chart Types
+- `top-free` — Top Free Apps
+- `top-paid` — Top Paid Apps
+- `top-grossing` — Top Grossing Apps
+- `new-free` — New Free Apps
+- `new-paid` — New Paid Apps
+
+## API Reference
+
+### `start_urls(params: dict) -> list[str]`
+
+Build initial URL(s) to fetch from user parameters.
+
+**Parameters:**
+- `params` (dict): Configuration dictionary with keys:
+  - `mode` (str, required): One of `"search"`, `"details"`, `"reviews"`, `"charts"`
+  - `searchTerm` (str, optional): Keyword for search mode (default: `"photo editor"`)
+  - `appIds` (list[str], optional): App IDs or App Store URLs for details/reviews modes (default: `["389801252"]`)
+  - `chartType` (str, optional): Chart type for charts mode (default: `"top-free"`)
+  - `country` (str, optional): Two-letter country code (default: `"us"`)
+
+**Returns:** List of URLs to fetch initially.
+
+**Example:**
+```python
+start_urls({"mode": "search", "searchTerm": "fitness", "country": "gb"})
+# ["https://itunes.apple.com/search?term=fitness&country=gb&entity=software&limit=200"]
+```
+
+---
+
+### `process(text: str, url: str) -> list[dict]`
+
+Parse a single fetched response into structured records.
+
+**Parameters:**
+- `text` (str): Raw response body (JSON)
+- `url` (str): The URL that was fetched (used to determine response type)
+
+**Returns:** List of record dictionaries. Each record has exactly these fields:
+
+**App Records (search, details, charts):**
+| Field | Type | Description |
+|-------|------|-------------|
+| `appId` | str | Numeric App Store ID |
+| `appName` | str | App display name |
+| `developer` | str | Developer/seller name |
+| `price` | dict | `{"amount": float, "currency": str, "formatted": str}` |
+| `rating` | dict | `{"value": float, "count": int}` |
+| `description` | str | App description |
+| `screenshotUrls` | list[str] | Screenshot image URLs |
+| `supportedDevices` | list[str] | e.g., `["iphone", "ipad", "mac"]` |
+| `country` | str | Two-letter country code |
+
+**Review Records (reviews mode):**
+| Field | Type | Description |
+|-------|------|-------------|
+| `reviewId` | str | Unique review identifier |
+| `title` | str | Review title |
+| `content` | str | Review text |
+| `rating` | int | 1–5 star rating |
+| `author` | str | Review author name (public) |
+| `date` | str | ISO 8601 timestamp |
+| `appVersion` | str | App version reviewed |
+
+**Example:**
+```python
+records = process(json_text, "https://itunes.apple.com/search?term=photo+editor&country=us")
+# [{
+#     "appId": "389801252",
+#     "appName": "Photo Editor Pro",
+#     "developer": "Example Inc.",
+#     "price": {"amount": 0.0, "currency": "USD", "formatted": "Free"},
+#     "rating": {"value": 4.7, "count": 12345},
+#     "description": "Edit photos like a pro...",
+#     "screenshotUrls": ["https://.../1.jpg", "https://.../2.jpg"],
+#     "supportedDevices": ["iphone", "ipad"],
+#     "country": "us"
+# }]
+```
+
+---
+
+### `next_urls(text: str, url: str) -> list[str]`
+
+Extract further URLs to fetch for pagination.
+
+**Parameters:**
+- `text` (str): Raw response body (JSON)
+- `url` (str): The URL that was fetched
+
+**Returns:** List of next-page URLs, empty if no more pages.
+
+**Behavior by mode:**
+- **search**: Uses `offset`/`limit` pagination until `resultCount` is reached
+- **details**: No pagination (single request per app ID)
+- **reviews**: Follows RSS `link[rel="next"]` for paginated review feeds
+- **charts**: No pagination (fixed limit feed)
+
+**Example:**
+```python
+next_pages = next_urls(search_response_text, search_url)
+# ["https://itunes.apple.com/search?term=photo+editor&country=us&limit=200&offset=200"]
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT License — see LICENSE for details.

apple_app_store_scraper_lite-0.1.0/README.md

@@ -0,0 +1,188 @@
+# Apple App Store Scraper Lite
+
+> **Run it hosted, no setup:** [Apple App Store Scraper Lite on Apify](https://apify.com/Redbaron/apple-app-store-scraper-lite) — pay per result, nothing to install or maintain.
+
+A lightweight, pure-Python library for scraping Apple App Store data via the iTunes API. Supports searching for apps, getting app details, extracting reviews, and discovering top charts — all without a browser, using only standard library HTTP requests.
+
+## Features
+
+- **Search apps** by keyword with full metadata (name, developer, price, rating, description, screenshots, supported devices)
+- **Get app details** by App Store ID or URL
+- **Extract reviews** with ratings, titles, content, author, date, and app version
+- **Discover top charts** (free, paid, grossing, new releases) by country
+- **Pure Python** — no external dependencies, no browser automation
+- **Pagination support** — automatically follows next-page links
+- **Privacy-safe** — never returns personal data (emails, phones, usernames beyond public review author names)
+
+## Installation
+
+```bash
+pip install apple-app-store-scraper-lite-0.1.0-py3-none-any.whl
+```
+
+Or install from source:
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from apple_app_store_scraper_lite import start_urls, process, next_urls
+import urllib.request
+import json
+
+# 1. Build start URLs from your parameters
+params = {
+    "mode": "search",
+    "searchTerm": "photo editor",
+    "country": "us"
+}
+urls = start_urls(params)
+print(f"Fetching: {urls[0]}")
+
+# 2. Fetch the response (using stdlib urllib)
+with urllib.request.urlopen(urls[0]) as response:
+    text = response.read().decode("utf-8")
+
+# 3. Parse into structured records
+records = process(text, urls[0])
+print(f"Found {len(records)} apps")
+for app in records[:3]:
+    print(f"  - {app['appName']} ({app['appId']}) by {app['developer']} — {app['price']['formatted']} — ⭐ {app['rating']['value']}")
+
+# 4. Follow pagination if needed
+for next_url in next_urls(text, urls[0]):
+    with urllib.request.urlopen(next_url) as response:
+        more_text = response.read().decode("utf-8")
+    more_records = process(more_text, next_url)
+    print(f"Next page: {len(more_records)} more apps")
+```
+
+## Modes
+
+| Mode | Description | Required Params | Optional Params |
+|------|-------------|-----------------|-----------------|
+| `search` | Search apps by keyword | `mode`, `searchTerm` | `country` (default: `us`) |
+| `details` | Get full app metadata | `mode`, `appIds` | `country` (default: `us`) |
+| `reviews` | Extract user reviews | `mode`, `appIds` | `country` (default: `us`) |
+| `charts` | Top charts by category | `mode` | `chartType` (default: `top-free`), `country` (default: `us`) |
+
+### Chart Types
+- `top-free` — Top Free Apps
+- `top-paid` — Top Paid Apps
+- `top-grossing` — Top Grossing Apps
+- `new-free` — New Free Apps
+- `new-paid` — New Paid Apps
+
+## API Reference
+
+### `start_urls(params: dict) -> list[str]`
+
+Build initial URL(s) to fetch from user parameters.
+
+**Parameters:**
+- `params` (dict): Configuration dictionary with keys:
+  - `mode` (str, required): One of `"search"`, `"details"`, `"reviews"`, `"charts"`
+  - `searchTerm` (str, optional): Keyword for search mode (default: `"photo editor"`)
+  - `appIds` (list[str], optional): App IDs or App Store URLs for details/reviews modes (default: `["389801252"]`)
+  - `chartType` (str, optional): Chart type for charts mode (default: `"top-free"`)
+  - `country` (str, optional): Two-letter country code (default: `"us"`)
+
+**Returns:** List of URLs to fetch initially.
+
+**Example:**
+```python
+start_urls({"mode": "search", "searchTerm": "fitness", "country": "gb"})
+# ["https://itunes.apple.com/search?term=fitness&country=gb&entity=software&limit=200"]
+```
+
+---
+
+### `process(text: str, url: str) -> list[dict]`
+
+Parse a single fetched response into structured records.
+
+**Parameters:**
+- `text` (str): Raw response body (JSON)
+- `url` (str): The URL that was fetched (used to determine response type)
+
+**Returns:** List of record dictionaries. Each record has exactly these fields:
+
+**App Records (search, details, charts):**
+| Field | Type | Description |
+|-------|------|-------------|
+| `appId` | str | Numeric App Store ID |
+| `appName` | str | App display name |
+| `developer` | str | Developer/seller name |
+| `price` | dict | `{"amount": float, "currency": str, "formatted": str}` |
+| `rating` | dict | `{"value": float, "count": int}` |
+| `description` | str | App description |
+| `screenshotUrls` | list[str] | Screenshot image URLs |
+| `supportedDevices` | list[str] | e.g., `["iphone", "ipad", "mac"]` |
+| `country` | str | Two-letter country code |
+
+**Review Records (reviews mode):**
+| Field | Type | Description |
+|-------|------|-------------|
+| `reviewId` | str | Unique review identifier |
+| `title` | str | Review title |
+| `content` | str | Review text |
+| `rating` | int | 1–5 star rating |
+| `author` | str | Review author name (public) |
+| `date` | str | ISO 8601 timestamp |
+| `appVersion` | str | App version reviewed |
+
+**Example:**
+```python
+records = process(json_text, "https://itunes.apple.com/search?term=photo+editor&country=us")
+# [{
+#     "appId": "389801252",
+#     "appName": "Photo Editor Pro",
+#     "developer": "Example Inc.",
+#     "price": {"amount": 0.0, "currency": "USD", "formatted": "Free"},
+#     "rating": {"value": 4.7, "count": 12345},
+#     "description": "Edit photos like a pro...",
+#     "screenshotUrls": ["https://.../1.jpg", "https://.../2.jpg"],
+#     "supportedDevices": ["iphone", "ipad"],
+#     "country": "us"
+# }]
+```
+
+---
+
+### `next_urls(text: str, url: str) -> list[str]`
+
+Extract further URLs to fetch for pagination.
+
+**Parameters:**
+- `text` (str): Raw response body (JSON)
+- `url` (str): The URL that was fetched
+
+**Returns:** List of next-page URLs, empty if no more pages.
+
+**Behavior by mode:**
+- **search**: Uses `offset`/`limit` pagination until `resultCount` is reached
+- **details**: No pagination (single request per app ID)
+- **reviews**: Follows RSS `link[rel="next"]` for paginated review feeds
+- **charts**: No pagination (fixed limit feed)
+
+**Example:**
+```python
+next_pages = next_urls(search_response_text, search_url)
+# ["https://itunes.apple.com/search?term=photo+editor&country=us&limit=200&offset=200"]
+```
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+## License
+
+MIT License — see LICENSE for details.

apple_app_store_scraper_lite-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apple-app-store-scraper-lite"
+version = "0.1.0"
+description = "A lightweight, pure-Python library for scraping Apple App Store data via iTunes API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Apple App Store Scraper Lite Contributors"}
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["apple_app_store_scraper_lite*"]
+
+[tool.setuptools.package-data]
+"*" = ["fixtures/*.json"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov>=4.0"]
+
+[project.urls]
+Homepage = "https://apify.com/Redbaron/apple-app-store-scraper-lite"

apple_app_store_scraper_lite-0.1.0/setup.cfg

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

apple_app_store_scraper_lite-0.1.0/src/apple_app_store_scraper_lite/__init__.py

@@ -0,0 +1,20 @@
+"""
+Apple App Store Scraper Lite
+
+A lightweight, pure-Python library for scraping Apple App Store data via the iTunes API.
+Supports searching for apps, getting app details, extracting reviews, and discovering top charts.
+
+Public API:
+    - start_urls: Build initial URLs from user parameters
+    - process: Parse a fetched response into structured records
+    - next_urls: Get pagination URLs for the next page of results
+"""
+
+from __future__ import annotations
+
+from .parsers import process
+from .pagination import next_urls
+from .urls import start_urls
+
+__all__ = ["start_urls", "process", "next_urls"]
+__version__ = "0.1.0"

apple_app_store_scraper_lite-0.1.0/src/apple_app_store_scraper_lite/pagination.py

@@ -0,0 +1,116 @@
+"""
+Pagination handling for Apple App Store iTunes API responses.
+
+Pure functions that extract next-page URLs from responses.
+No network I/O, no side effects.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Any
+
+
+def _extract_next_from_search(text: str, url: str) -> list[str]:
+    """Extract next page URL from search API response."""
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+
+    # iTunes search API doesn't have standard pagination in response
+    # But we can paginate by offset if resultCount > limit
+    result_count = data.get("resultCount", 0)
+    results = data.get("results", [])
+
+    if not isinstance(results, list) or len(results) == 0:
+        return []
+
+    # If we got fewer results than limit, we're done
+    # Default limit is 200, but could be overridden
+    parsed = urllib.parse.urlparse(url)
+    query = urllib.parse.parse_qs(parsed.query)
+    limit = int(query.get("limit", ["200"])[0])
+
+    if len(results) < limit:
+        return []
+
+    # Calculate next offset
+    offset = int(query.get("offset", ["0"])[0])
+    next_offset = offset + limit
+
+    # Don't paginate beyond resultCount
+    if next_offset >= result_count:
+        return []
+
+    # Build next URL with updated offset
+    next_query = dict(query)
+    next_query["offset"] = [str(next_offset)]
+    next_url = urllib.parse.urlunparse((
+        parsed.scheme,
+        parsed.netloc,
+        parsed.path,
+        parsed.params,
+        urllib.parse.urlencode(next_query, doseq=True),
+        parsed.fragment
+    ))
+    return [next_url]
+
+
+def _extract_next_from_lookup(text: str, url: str) -> list[str]:
+    """Lookup API doesn't paginate - single request per app ID."""
+    return []
+
+
+def _extract_next_from_reviews(text: str, url: str) -> list[str]:
+    """Extract next page URL from reviews RSS feed."""
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return []
+
+    feed = data.get("feed", {})
+    links = feed.get("link", [])
+    if not isinstance(links, list):
+        return []
+
+    # Find the 'next' link
+    for link in links:
+        if isinstance(link, dict):
+            rel = link.get("rel")
+            href = link.get("href")
+            if rel == "next" and href:
+                return [href]
+    return []
+
+
+def _extract_next_from_charts(text: str, url: str) -> list[str]:
+    """Charts RSS feed doesn't typically paginate (fixed limit)."""
+    return []
+
+
+def next_urls(text: str, url: str) -> list[str]:
+    """
+    Extract further URLs to fetch for pagination.
+
+    Args:
+        text: Raw response text (JSON)
+        url: The URL that was fetched
+
+    Returns:
+        List of next page URLs, empty if no more pages.
+    """
+    if not text or not isinstance(text, str):
+        return []
+
+    if "/search?" in url:
+        return _extract_next_from_search(text, url)
+    elif "/lookup?" in url:
+        return _extract_next_from_lookup(text, url)
+    elif "/customerreviews/" in url:
+        return _extract_next_from_reviews(text, url)
+    elif "/rss/" in url:
+        return _extract_next_from_charts(text, url)
+    else:
+        return []