### Quick Start: Initialize and Get Suggestions

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Initializes the scraper and demonstrates fetching simple and nested search suggestions for a given term.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get suggestions
suggestions = scraper.suggest_analyze("video", count=5)
print(suggestions)
# ['video player', 'video editor', 'video downloader', 'video maker', 'video call']

# Get nested suggestions
nested = scraper.suggest_nested("video", count=3)
for term, suggestions in nested.items():
    print(f"{term}: {suggestions}")
```

--------------------------------

### GPlay Scraper Quick Start Examples

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/README.md

Demonstrates how to initialize the scraper and use various methods for app data retrieval, search, reviews, developer portfolios, top charts, similar apps, and search suggestions. Each example shows a common use case for its respective method.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# App Methods
app_info = scraper.app_get_fields("com.whatsapp", ["title", "score", "installs"])
print(f"{app_info['title']} — {app_info['score']}★ — {app_info['installs']} installs")

# Search Methods
search_results = scraper.search_get_fields("fitness tracker", ["title", "developer"], count=20)
for app in search_results[:3]:
    print(f"{app['title']} by {app['developer']}")

# Reviews Methods
reviews = scraper.reviews_get_fields("com.whatsapp", ["userName", "score"], count=100, sort="NEWEST")
print(f"Latest reviewer: {reviews[0]['userName']} rated {reviews[0]['score']}★")

# Developer Methods
portfolio = scraper.developer_get_fields("5700313618786177705", ["title", "score"], count=50)
print(f"Developer apps tracked: {len(portfolio)}")

# List Methods
top_free = scraper.list_get_fields("TOP_FREE", "GAME", ["title", "score"], count=50)
print(f"Top game: {top_free[0]['title']} ({top_free[0]['score']}★)")

# Similar Methods
competitors = scraper.similar_get_fields("com.whatsapp", ["title", "score"], count=30)
print(f"Similar app example: {competitors[0]['title']} ({competitors[0]['score']}★)")

# Suggest Methods
suggestions = scraper.suggest_nested("photo editor", count=10)
print(f"Related suggestions: {list(suggestions.keys())[:3]}")
```

--------------------------------

### Run All Example Scripts

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/examples/README.md

Execute any of the provided example scripts to demonstrate the functionality of the gplay-scraper library.

```bash
python examples/app_methods_example.py
```

```bash
python examples/search_methods_example.py
```

```bash
python examples/reviews_methods_example.py
```

```bash
python examples/developer_methods_example.py
```

```bash
python examples/list_methods_example.py
```

```bash
python examples/similar_methods_example.py
```

```bash
python examples/suggest_methods_example.py
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/contributing.md

Clone the repository, navigate to the project directory, and install development dependencies using uv.

```bash
git clone https://github.com/yourusername/gplay-scraper.git
cd gplay-scraper
uv sync --extra dev  # creates .venv and installs dev dependencies
```

--------------------------------

### Install GPlay Scraper

Source: https://context7.com/elmissouri16/gplay-scraper/llms.txt

Install the library using pip or uv. For local development, use an editable install.

```bash
pip install "git+https://github.com/elmissouri16/gplay-scraper.git"
```

```bash
uv pip install "git+https://github.com/elmissouri16/gplay-scraper.git"
```

```bash
pip install -e .
```

--------------------------------

### Install gplay-scraper with uv

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/installation.md

Optional installation using uv, a fast Python package installer. Recommended for contributors.

```bash
uv pip install gplay-scraper
```

--------------------------------

### Practical Example: Top Free Games Analysis

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/LIST_METHODS.md

Analyzes top free games to calculate the total count and average rating, then prints the top 5 games with their score and install count. Useful for quick statistical insights.

```python
top_games = scraper.list_analyze("TOP_FREE", "GAME", count=100)

print(f"Total games: {len(top_games)}")
print(f"Average rating: {sum(a['score'] for a in top_games if a['score']) / len(top_games):.2f}")
print(f"\nTop 5 games:")
for i, game in enumerate(top_games[:5], 1):
    print(f"{i}. {game['title']} - {game['score']}★ - {game['installs']} installs")
```

--------------------------------

### Quick Start: Get Multiple Review Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Retrieves a specified list of fields (e.g., 'userName', 'score', 'content') from multiple reviews.

```python
# Get multiple fields
reviews = scraper.reviews_get_fields("com.whatsapp", ["userName", "score", "content"], count=50)
print(reviews)
```

--------------------------------

### Quick Start: GPlay Scraper Usage

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/index.md

Demonstrates basic usage of the GPlayScraper library for fetching app data, search results, and reviews. Ensure the library is installed before running.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# App methods
app_data = scraper.app_analyze("com.whatsapp", lang="en", country="us")
print(app_data["title"])

# Search methods
top_apps = scraper.search_get_fields("productivity apps", ["title", "developer"], count=10, lang="en", country="us")
print(top_apps[:3])

# Reviews methods
reviews = scraper.reviews_get_fields("com.whatsapp", ["userName", "score"], count=10, sort="NEWEST")
print(reviews[:3])
```

--------------------------------

### Formatting Tips: Display App Info

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Example of how to format the data returned by `app_get_field` or `app_get_fields` for user-friendly display.

```python
info = scraper.app_get_fields("com.whatsapp", ["title", "score", "free"])
print(f"{info['title']} — {info['score']}★ — {'Free' if info['free'] else 'Paid'}")
```

--------------------------------

### Install gplay-scraper

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README.md

Install the library directly from the GitHub repository using pip or uv. For local development, use the editable mode.

```bash
pip install "git+https://github.com/elmissouri16/gplay-scraper.git"
# Alternatively with uv
uv pip install "git+https://github.com/elmissouri16/gplay-scraper.git"

# Develop locally in editable mode
pip install -e .
# or
uv pip install --editable .
```

--------------------------------

### Return Format: Simple Suggestions List

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Example of the output format for simple search suggestions, returned as a list of strings.

```python
['video player', 'video editor', 'video downloader', 'video maker', 'video call']
```

--------------------------------

### Practical Example: ASO Keyword Discovery

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Discovers keywords up to a specified depth starting from a seed term. It fetches level 1 suggestions and then level 2 suggestions for a subset of level 1 terms.

```python
import json

def discover_keywords(seed_term, depth=2):
    """Discover keywords with specified depth"""
    keywords = {}
    
    # Level 1
    level1 = scraper.suggest_analyze(seed_term, count=10)
    keywords[seed_term] = level1
    
    if depth > 1:
        # Level 2
        for term in level1[:5]:  # Limit to avoid too many requests
            level2 = scraper.suggest_analyze(term, count=5)
            keywords[term] = level2
    
    return keywords

keywords = discover_keywords("game", depth=2)
print(json.dumps(keywords, indent=2))
```

--------------------------------

### Find Similar Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Discover apps that are similar to a given app ID. This example finds apps similar to WhatsApp and displays their titles, developers, ratings, and install counts.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
app_id = "com.whatsapp"

similar = scraper.similar_analyze(app_id, count=30, lang="en", country="us")

print("Apps similar to WhatsApp:")
for app in similar[:10]:
    print(f"  {app['title']} by {app['developer']}")
    print(f"    Rating: {app['score']} | {app['installs']}")
```

--------------------------------

### Development Installation of gplay-scraper

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/installation.md

Install gplay-scraper in editable mode for development. Includes instructions for both pip and uv, and how to include development extras.

```bash
git clone https://github.com/elmissouri16/gplay-scraper.git
cd gplay-scraper
pip install -e .
# or, using uv:
uv pip install --editable .

# include dev extras for contributors
uv sync --extra dev
```

--------------------------------

### Practical Example: Keyword Research

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Demonstrates how to expand a list of base keywords by fetching suggestions for each, useful for initial keyword research.

```python
base_keywords = ["fitness", "workout", "exercise"]
all_keywords = set()

for keyword in base_keywords:
    suggestions = scraper.suggest_analyze(keyword, count=10)
    all_keywords.update(suggestions)
    print(f"{keyword}: {len(suggestions)} suggestions")

print(f"\nTotal unique keywords: {len(all_keywords)}")
print("Sample keywords:", list(all_keywords)[:10])
```

--------------------------------

### Install gplay-scraper from PyPI

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/installation.md

Use this command to install the latest stable version of gplay-scraper from the Python Package Index.

```bash
pip install gplay-scraper
```

--------------------------------

### Practical Example: Compare App Versions

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Compares app versions by grouping reviews by 'appVersion' and calculating average scores for versions with at least 5 reviews.

```python
reviews = scraper.reviews_get_fields("com.whatsapp", ["appVersion", "score"], count=300)

# Group by version
version_scores = {}
for review in reviews:
    version = review['appVersion'] or "Unknown"
    if version not in version_scores:
        version_scores[version] = []
    version_scores[version].append(review['score'])

# Show version ratings
for version, scores in sorted(version_scores.items()):
    if len(scores) >= 5:  # Only versions with 5+ reviews
        avg = sum(scores) / len(scores)
        print(f"v{version}: {avg:.2f}★ ({len(scores)} reviews)")
```

--------------------------------

### Verify gplay-scraper Installation

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/installation.md

Run this Python script to confirm that gplay-scraper is installed correctly and can fetch basic app information.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
data = scraper.app_analyze("com.whatsapp")
print(f"Success! Retrieved: {data['title']}")

title = scraper.app_get_field("com.whatsapp", "title")
print(f"Title preview: {title}")  # alternate smoke test
```

--------------------------------

### Practical Example: Export Developer Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Fetches all apps for a developer using `developer_analyze` and exports the data to a JSON file named 'developer_apps.json'.

```python
import json

dev_id = "5700313618786177705"
apps = scraper.developer_analyze(dev_id)

with open('developer_apps.json', 'w') as f:
    json.dump(apps, f, indent=2)

print(f"Exported {len(apps)} apps to developer_apps.json")
```

--------------------------------

### Practical Example: Analyze Developer Portfolio

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Calculates and prints the total number of apps, average rating, and counts of free and paid apps for a given developer ID.

```python
dev_id = "5700313618786177705"
apps = scraper.developer_analyze(dev_id)

print(f"Total apps: {len(apps)}")
print(f"Average rating: {sum(a['score'] for a in apps if a['score']) / len(apps):.2f}")
print(f"Free apps: {sum(1 for a in apps if a['free'])}")
print(f"Paid apps: {sum(1 for a in apps if not a['free'])}")
```

--------------------------------

### Quick Start: Extract and Print Reviews

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Initializes the scraper and demonstrates fetching and printing basic review information like username, score, and content.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get reviews
reviews = scraper.reviews_analyze("com.whatsapp", count=100, sort="NEWEST")
for review in reviews[:5]:
    print(f"{review['userName']}: {review['score']}★")
    print(f"  {review['content'][:100]}...")
```

--------------------------------

### Market Positioning Example

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Analyze market positioning by categorizing similar apps into free and paid, then calculating average ratings for each category.

```python
app_id = "com.whatsapp"
similar = scraper.similar_get_fields(app_id, ["title", "free", "price", "score"], count=50)

free_apps = [app for app in similar if app['free']]
paid_apps = [app for app in similar if not app['free']]

print(f"Market Analysis for {app_id}:")
print(f"  Free competitors: {len(free_apps)}")
print(f"  Paid competitors: {len(paid_apps)}")
if free_apps:
    print(f"  Free avg rating: {sum(a['score'] or 0 for a in free_apps)/len(free_apps):.2f}★")
if paid_apps:
    print(f"  Paid avg rating: {sum(a['score'] or 0 for a in paid_apps)/len(paid_apps):.2f}★")
```

--------------------------------

### Practical Example: Trending Search Terms

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Fetches trending search terms for a predefined list of categories, showing the top suggestions for each.

```python
categories = ["game", "social", "productivity", "photo", "music"]
trending = {}

for category in categories:
    suggestions = scraper.suggest_analyze(category, count=5)
    trending[category] = suggestions
    print(f"{category}: {', '.join(suggestions[:3])}...")
```

--------------------------------

### Pagination Example with Different Counts

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SEARCH_METHODS.md

Illustrates how to retrieve different numbers of search results (20, 50, 100) for the same query using the 'count' parameter.

```python
# Get more results
results_20 = scraper.search_analyze("game", count=20)
results_50 = scraper.search_analyze("game", count=50)
results_100 = scraper.search_analyze("game", count=100)

print(f"20 results: {len(results_20)}")
print(f"50 results: {len(results_50)}")
print(f"100 results: {len(results_100)}")
```

--------------------------------

### Practical Example: Find Top-Rated Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Fetches app titles and scores, then sorts them to display the top 5 highest-rated apps from a developer.

```python
dev_id = "5700313618786177705"
apps = scraper.developer_get_fields(dev_id, ["title", "score"])

# Sort by rating
top_apps = sorted(apps, key=lambda x: x['score'] or 0, reverse=True)[:5]
for i, app in enumerate(top_apps, 1):
    print(f"{i}. {app['title']}: {app['score']}★")
```

--------------------------------

### Search Methods: Analyze, Get Field, Get Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Searches for apps by a query and retrieves data using analyze, get_field, and get_fields. Demonstrates fetching titles and developers.

```python
query = "social media"

results = scraper.search_analyze(query, count=20, lang="en", country="us")
for app in results:
    print(f"{app['title']} - {app['developer']}")

titles = scraper.search_get_field(query, "title", count=10)
data = scraper.search_get_fields(query, ["title", "score"], count=10)
for idx, app in enumerate(data[:5], 1):
    print(f"{idx}. {app['title']} — {app.get('score', 'N/A')}★")
```

--------------------------------

### Practical Example: Competitor Keyword Analysis

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Analyzes keywords related to competitor apps by fetching suggestions for each app name and then finding common keywords among them.

```python
competitor_apps = ["whatsapp", "telegram", "signal"]
all_suggestions = {}

for app in competitor_apps:
    suggestions = scraper.suggest_analyze(app, count=10)
    all_suggestions[app] = suggestions
    print(f"{app}: {len(suggestions)} suggestions")

# Find common keywords
common = set(all_suggestions[competitor_apps[0]])
for app in competitor_apps[1:]:
    common &= set(all_suggestions[app])

print(f"\nCommon keywords: {common}")
```

--------------------------------

### Practical Example: Find Common Issues

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Identifies and displays common issues by filtering for low-rated reviews. Fetches 'score' and 'content', sorted by rating.

```python
reviews = scraper.reviews_get_fields("com.whatsapp", ["score", "content"], count=100, sort="RATING")

# Get low-rated reviews
low_rated = [r for r in reviews if r['score'] <= 2]

print(f"Found {len(low_rated)} low-rated reviews:")
for review in low_rated[:10]:
    print(f"- {review['content'][:100]}...")
```

--------------------------------

### Analyze App: Get All Data

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Retrieve all available information for a given app ID. Supports custom asset sizes for media.

```python
data = scraper.app_analyze("com.whatsapp")
# Returns: {'appId': 'com.whatsapp', 'title': 'WhatsApp Messenger', ...}

# With custom image sizes
data = scraper.app_analyze("com.whatsapp", assets="LARGE")
# Returns same data but with larger image URLs (2048px)
```

--------------------------------

### Multi-Region Search Example

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SEARCH_METHODS.md

Shows how to perform searches in different countries and languages to gather region-specific app data. Fetches 20 results per region.

```python
# Search in different regions
us_results = scraper.search_analyze("vpn", country="us", count=20)
uk_results = scraper.search_analyze("vpn", country="gb", count=20)
jp_results = scraper.search_analyze("vpn", country="jp", lang="ja", count=20)

print(f"US: {len(us_results)} results")
print(f"UK: {len(uk_results)} results")
print(f"JP: {len(jp_results)} results")
```

--------------------------------

### Practical Example: Sentiment Analysis

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Analyzes review data to calculate rating distribution and average rating. Requires fetching 'score' and 'content' fields.

```python
reviews = scraper.reviews_get_fields("com.whatsapp", ["score", "content"], count=200)

# Rating distribution
rating_dist = {1: 0, 2: 0, 3: 0, 4: 0, 5: 0}
for review in reviews:
    rating_dist[review['score']] += 1

print("Rating Distribution:")
for rating, count in rating_dist.items():
    print(f"{rating}★: {'█' * count} ({count})")

# Average rating
avg = sum(r['score'] for r in reviews) / len(reviews)
print(f"\nAverage: {avg:.2f}★")
```

--------------------------------

### Competitive Analysis Example

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Analyze competitors by fetching similar apps and displaying their titles, scores, and developers. Calculate the average competitor rating.

```python
app_id = "com.whatsapp"
similar = scraper.similar_get_fields(app_id, ["title", "score", "developer"], count=30)

print(f"Competitors of {app_id}:")
for i, app in enumerate(similar[:10], 1):
    print(f"{i}. {app['title']}: {app['score']}★ by {app['developer']}")

# Calculate average competitor rating
avg_score = sum(app['score'] or 0 for app in similar) / len(similar)
print(f"\nAverage competitor rating: {avg_score:.2f}★")
```

--------------------------------

### Practical Example: Deep Keyword Mining

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Uses `suggest_nested` to build a keyword tree for a given term, allowing for in-depth exploration of related keywords.

```python
term = "photo editor"
nested = scraper.suggest_nested(term, count=5)

print(f"Keyword tree for '{term}':")
for parent, children in nested.items():
    print(f"\n{parent}:")
    for child in children:
        print(f"  - {child}")
```

--------------------------------

### Practical Example: Track Review Trends

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Analyzes review timestamps ('at') and scores to calculate monthly average ratings. Requires importing the `datetime` module.

```python
from datetime import datetime

reviews = scraper.reviews_get_fields("com.whatsapp", ["at", "score"], count=500, sort="NEWEST")

# Group by month
monthly_scores = {}
for review in reviews:
    date = datetime.fromisoformat(review['at'])
    month_key = date.strftime("%Y-%m")
    
    if month_key not in monthly_scores:
        monthly_scores[month_key] = []
    monthly_scores[month_key].append(review['score'])

# Calculate monthly averages
for month, scores in sorted(monthly_scores.items()):
    avg = sum(scores) / len(scores)
    print(f"{month}: {avg:.2f}★ ({len(scores)} reviews)")
```

--------------------------------

### Competitive Analysis: Compare Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Iterate through a list of app IDs to fetch and display key metrics like title, score, and installs for comparative analysis.

```python
apps = ["com.whatsapp", "com.telegram", "com.viber"]
for app_id in apps:
    data = scraper.app_get_fields(app_id, ["title", "score", "realInstalls"])
    print(f"{data['title']}: {data['score']}★ - {data['realInstalls']:,} installs")
```

--------------------------------

### Quick Start: Get Specific Review Field

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Fetches only a specific field (e.g., 'score') from multiple reviews and calculates the average.

```python
# Get specific fields
scores = scraper.reviews_get_field("com.whatsapp", "score", count=100)
print(f"Average: {sum(scores)/len(scores):.2f}★")
```

--------------------------------

### ASO Keyword Research Workflow

Source: https://context7.com/elmissouri16/gplay-scraper/llms.txt

An example workflow for conducting App Store Optimization (ASO) keyword research by fetching suggestions for multiple seed keywords and printing them.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# ASO keyword research workflow
seed_keywords = ["meditation", "sleep", "mindfulness"]
keyword_map = {}
for seed in seed_keywords:
    keyword_map[seed] = scraper.suggest_analyze(seed, count=10, lang="en", country="us")
    for kw in keyword_map[seed]:
        print(kw)
```

--------------------------------

### Analyze Developer Portfolio

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Retrieve a list of all apps published by a specific developer, including their titles, scores, and install counts. This example lists apps for WhatsApp Inc.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
dev_id = "5700313618786177705"  # WhatsApp Inc.

apps = scraper.developer_analyze(dev_id, count=50, lang="en", country="us")

print(f"Developer has {len(apps)} apps:")
for app in apps:
    print(f"  {app['title']}: {app['score']} stars - {app['installs']}")
```

--------------------------------

### Practical Example: Compare Free vs Paid Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Retrieves app details and compares the number and average rating of free apps versus paid apps from a developer.

```python
dev_id = "5700313618786177705"
apps = scraper.developer_get_fields(dev_id, ["title", "free", "price", "score"])

free_apps = [a for a in apps if a['free']]
paid_apps = [a for a in apps if not a['free']]

print(f"Free apps: {len(free_apps)} (avg rating: {sum(a['score'] or 0 for a in free_apps)/len(free_apps):.2f})")
print(f"Paid apps: {len(paid_apps)} (avg rating: {sum(a['score'] or 0 for a in paid_apps)/len(paid_apps):.2f})")
```

--------------------------------

### Get Search Suggestions

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Retrieve search suggestions for a given query, including both direct suggestions and nested related terms. This example shows suggestions for 'photo editor' and 'fitness'.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

suggestions = scraper.suggest_analyze("photo editor", count=10, lang="en", country="us")
for suggestion in suggestions:
    print(f"  - {suggestion}")

nested = scraper.suggest_nested("fitness", count=5, lang="en", country="us")
for term, related in nested.items():
    print(f"{term}: {related}")
```

--------------------------------

### Quick Start: Scrape Top Charts

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/LIST_METHODS.md

Initialize the scraper and demonstrate fetching top free apps, extracting specific fields, and retrieving multiple fields for paid apps.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get top free apps
top_free = scraper.list_analyze("TOP_FREE", "GAME", count=50)
for app in top_free[:10]:
    print(f"{app['title']}: {app['installs']} installs")

# Get specific fields
titles = scraper.list_get_field("TOP_FREE", "title", "APPLICATION")
print(titles)

# Get multiple fields
apps = scraper.list_get_fields("TOP_PAID", ["title", "price", "score"], "GAME")
print(apps)
```

--------------------------------

### Quick Start: Search and Analyze Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SEARCH_METHODS.md

Initialize the scraper and perform a basic search for apps by keyword. This method returns a list of dictionaries, each containing detailed app information.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Search for apps
results = scraper.search_analyze("social media", count=20)
for app in results:
    print(f"{app['title']}: {app['score']}★ by {app['developer']}")

# Get specific fields
titles = scraper.search_get_field("fitness tracker", "title")
print(titles)

# Get multiple fields
apps = scraper.search_get_fields("photo editor", ["title", "score", "free"])
print(apps)
```

--------------------------------

### Quick Start: Scrape Similar Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Initialize the scraper and retrieve similar apps, then iterate and print their titles, scores, and developers. You can also fetch specific fields or multiple fields for the similar apps.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get similar apps
similar = scraper.similar_analyze("com.whatsapp", count=20)
for app in similar:
    print(f"{app['title']}: {app['score']}★ by {app['developer']}")

# Get specific fields
titles = scraper.similar_get_field("com.whatsapp", "title")
print(titles)

# Get multiple fields
apps = scraper.similar_get_fields("com.whatsapp", ["title", "score", "free"])
print(apps)
```

--------------------------------

### Get App Suggestions

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/fields_reference.md

Use the `suggest_analyze` method to get a list of app suggestion strings based on a query. This is useful for autocompletion or related search terms.

```python
suggestions = scraper.suggest_analyze("fitness")
# ['fitness tracker', 'fitness app', 'fitness watch', ...]
```

--------------------------------

### GPlayScraper Initialization and Proxy Configuration

Source: https://context7.com/elmissouri16/gplay-scraper/llms.txt

Demonstrates how to initialize the GPlayScraper class with and without proxy support, and how to update proxy settings at runtime.

```APIDOC
## Initialization and Proxy Configuration

`GPlayScraper` is the single entry point. An optional `proxies` argument routes all HTTP traffic through a proxy; it can be updated at any time with `set_proxies()`.

```python
from gplay_scraper import GPlayScraper

# No proxy
scraper = GPlayScraper()

# Single proxy URL (applied to both HTTP and HTTPS)
scraper_proxy = GPlayScraper(proxies="http://127.0.0.1:8080")

# Scheme-specific proxies
scraper_split = GPlayScraper(
    proxies={
        "http": "http://corp-proxy.local:8080",
        "https": "http://secure-proxy.local:8443",
    }
)

# Update proxy at runtime
scraper_proxy.set_proxies({"https": "http://new-proxy.local:9090"})

# Remove proxy
scraper_proxy.set_proxies(None)
```
```

--------------------------------

### Get Single Field: App Score or Icon

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Fetch a specific field for an app. Useful for quickly getting a single piece of information like the score or an icon URL.

```python
score = scraper.app_get_field("com.whatsapp", "score")
# Returns: 4.2

# Get high-quality icon
icon = scraper.app_get_field("com.whatsapp", "icon", assets="ORIGINAL")
# Returns: URL with maximum image quality
```

--------------------------------

### Compare Multiple Apps Example

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Compare similar apps across multiple reference apps by iterating through a list of app IDs, fetching their similar apps, and storing the results.

```python
apps_to_compare = ["com.whatsapp", "com.telegram", "com.viber"]
all_similar = {}

for app_id in apps_to_compare:
    similar = scraper.similar_get_fields(app_id, ["appId", "title"], count=20)
    all_similar[app_id] = [app['appId'] for app in similar]
    print(f"{app_id}: {len(similar)} similar apps")
```

--------------------------------

### Developer Methods: Analyze, Get Field, Get Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Fetches all apps published by a developer using analyze, get_field, and get_fields. Demonstrates retrieving app titles and scores.

```python
dev_id = "5700313618786177705"  # WhatsApp Inc.

apps = scraper.developer_analyze(dev_id, count=20, lang="en", country="us")
for app in apps:
    print(f"{app['title']} - {app['score']} stars")

titles = scraper.developer_get_field(dev_id, "title", count=20)
summaries = scraper.developer_get_fields(dev_id, ["title", "score"], count=20)
print(summaries[:3])
```

--------------------------------

### Fetch App Fields with Custom Parameters

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/installation.md

Example of fetching specific fields for an app, specifying language and country. Also demonstrates searching for apps with custom parameters.

```python
summary = scraper.app_get_fields("com.whatsapp", ["title", "score"], lang="es", country="es")
print(summary)
results = scraper.search_get_fields("games", ["title", "developer"], count=50, lang="en", country="us")
print(results[:3])
```

--------------------------------

### Reviews Methods: Analyze, Get Field, Get Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Retrieves user reviews for an app using analyze, get_field, and get_fields. Shows how to fetch review scores and usernames.

```python
app_id = "com.whatsapp"

reviews = scraper.reviews_analyze(app_id, count=50, sort="NEWEST")
for review in reviews:
    print(f"{review['userName']}: {review['score']} stars")

scores = scraper.reviews_get_field(app_id, "score", count=100, sort="NEWEST")
recent = scraper.reviews_get_fields(app_id, ["userName", "score"], count=50, sort="NEWEST")
print(f"First reviewer: {recent[0]['userName']} ({recent[0]['score']}★)")
```

--------------------------------

### Quick Start: Analyze Developer Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Initialize the scraper and retrieve all apps from a developer, printing their titles and scores. Also shows how to fetch single or multiple specific fields.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get all apps from a developer
apps = scraper.developer_analyze("5700313618786177705")
for app in apps:
    print(f"{app['title']}: {app['score']}★")

# Get specific fields
titles = scraper.developer_get_field("5700313618786177705", "title")
print(titles)

# Get multiple fields
apps = scraper.developer_get_fields("5700313618786177705", ["title", "score", "free"])
print(apps)
```

--------------------------------

### Get Basic App Information

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Fetch core details like title, developer, genre, score, and pricing for an app. Also demonstrates fetching media assets like icons and screenshots.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
app_id = "com.whatsapp"

basic_info = scraper.app_get_fields(
    app_id,
    ["title", "developer", "genre", "score", "free"],
    lang="en",
    country="us",
)

media_info = scraper.app_get_fields(
    app_id,
    ["icon", "screenshots", "headerImage"],
    assets="LARGE",  # 2048px images
)

for field, value in basic_info.items():
    print(f"{field}: {value}")
```

--------------------------------

### App Methods: Analyze, Get Field, Get Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Extracts data for a specific app using analyze, get_field, and get_fields. Shows how to access title, rating, and other fields.

```python
app_id = "com.whatsapp"

data = scraper.app_analyze(app_id, lang="en", country="us")
print(f"Title: {data['title']}")
print(f"Rating: {data['score']}")

title = scraper.app_get_field(app_id, "title", lang="en", country="us")

fields = scraper.app_get_fields(app_id, ["title", "score", "installs"])
print(f"{fields['title']} — {fields['score']}★ — {fields['installs']} installs")
```

--------------------------------

### Quick Start: Scrape App Data

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Initialize the scraper and extract app data. Use `app_analyze` for all data, `app_get_field` for a single field, or `app_get_fields` for multiple specific fields.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

# Get all data
data = scraper.app_analyze("com.whatsapp")
print(data['title'], data['score'], data['installs'])

# Get specific fields
title = scraper.app_get_field("com.whatsapp", "title")
print(title)  # WhatsApp Messenger

# Get multiple fields
info = scraper.app_get_fields("com.whatsapp", ["title", "score", "developer"])
print(info)
```

--------------------------------

### List Analyze: Get Top Chart Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/LIST_METHODS.md

Retrieve a list of dictionaries representing top chart apps. Useful for getting a comprehensive overview of apps within a specific collection and category.

```python
apps = scraper.list_analyze("TOP_FREE", "GAME", count=50)
# Returns: [{'appId': '...', 'title': '...', 'installs': '...', ...}, ...]
```

--------------------------------

### Fetch App Icons with Different Asset Sizes

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Demonstrates how to fetch app icons in various sizes (SMALL, MEDIUM, LARGE, ORIGINAL) using the `assets` parameter. Also shows fetching multiple fields including images and videos.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
app_id = "com.whatsapp"

small_icon = scraper.app_get_field(app_id, "icon", assets="SMALL")       # https://...=w512
medium_icon = scraper.app_get_field(app_id, "icon", assets="MEDIUM")     # https://...=w1024
large_icon = scraper.app_get_field(app_id, "icon", assets="LARGE")       # https://...=w2048
original_icon = scraper.app_get_field(app_id, "icon", assets="ORIGINAL") # https://...=w9999

media = scraper.app_get_fields(
    app_id,
    ["icon", "screenshots", "headerImage", "videoImage"],
    assets="ORIGINAL",
)

print(f"Icon: {media['icon']}")
print(f"Screenshots: {len(media['screenshots'])} images")
print(f"Header: {media['headerImage']}")
```

--------------------------------

### List Get Fields: Extract Multiple Fields

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/LIST_METHODS.md

Retrieve multiple specified fields (e.g., 'title', 'price', 'score') for all apps in a chart collection. Useful for getting a structured subset of app information.

```python
apps = scraper.list_get_fields("TOP_PAID", ["title", "price", "score"], "GAME")
# Returns: [{'title': 'App 1', 'price': 4.99, 'score': 4.5}, ...]
```

--------------------------------

### Get Single Field

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Retrieves a single specific field for an app.

```APIDOC
## Get Single Field

### Description
Retrieves the value of a single, specific field for a given application.

### Method
`scraper.app_get_field(app_id, field, **kwargs)`

### Parameters
- `app_id` (str, required) - The package name of the app.
- `field` (str, required) - The name of the field to retrieve.
- `**kwargs` (optional) - Additional keyword arguments, such as `lang`, `country`, `assets`.

### Request Example
```python
small_icon = scraper.app_get_field("com.whatsapp", "icon", assets="SMALL")
# Returns: https://...=w512

large_icon = scraper.app_get_field("com.whatsapp", "icon", assets="LARGE")
# Returns: https://...=w2048

original_icon = scraper.app_get_field("com.whatsapp", "icon", assets="ORIGINAL")
# Returns: https://...=w9999
```

### Response Example
```json
"https://example.com/icon.png?w512"
```
```

--------------------------------

### Get High-Quality Media

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/APP_METHODS.md

Retrieves various media assets for an app, with options to specify image quality.

```APIDOC
## Get High-Quality Media

### Description
Fetches media assets such as icons, screenshots, and header images for an application, allowing selection of image quality.

### Method
`scraper.app_get_fields(app_id, fields, assets)`

### Parameters
- `app_id` (str, required) - The package name of the app.
- `fields` (List[str], required) - A list of media field names, e.g., `"icon"`, `"screenshots"`, `"headerImage"`, `"videoImage"`.
- `assets` (str, optional) - Specifies the desired quality of the image assets. Options: `"SMALL"`, `"MEDIUM"` (default), `"LARGE"`, `"ORIGINAL"`.

### Request Example
```python
app_id = "com.whatsapp"
# Get original quality images
media = scraper.app_get_fields(app_id, ["icon", "screenshots"], assets="ORIGINAL")
print(f"Icon: {media['icon']}")  # Maximum quality
print(f"Screenshots: {len(media['screenshots'])} images")

# Get small thumbnails for faster loading
thumbnails = scraper.app_get_fields(app_id, ["icon", "headerImage"], assets="SMALL")
print(f"Small icon: {thumbnails['icon']}")  # 512px
```

### Response Example
```json
{
  "icon": "https://example.com/icon.png?w9999",
  "screenshots": [
    "https://example.com/screenshot1.png?w9999",
    "https://example.com/screenshot2.png?w9999"
  ]
}
```
```

--------------------------------

### Analyze Similar Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Use `similar_analyze` to get a list of dictionaries, where each dictionary represents a similar app with its details.

```python
similar = scraper.similar_analyze("com.whatsapp", count=20)
# Returns: [{'appId': '...', 'title': '...', 'score': 4.5, ...}, ...]
```

--------------------------------

### Competitive App Analysis

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/examples.md

Analyze multiple apps to compare their ratings, scores, and other fields. This example ranks apps by their score.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()

apps = {
    "WhatsApp": "com.whatsapp",
    "Telegram": "org.telegram.messenger",
    "Signal": "org.thoughtcrime.securesms",
}

results = []
for name, app_id in apps.items():
    try:
        data = scraper.app_get_fields(
            app_id,
            ["title", "score", "ratings", "installs", "icon"],
            lang="en",
            country="us",
            assets="SMALL",
        )
        data["name"] = name
        results.append(data)
    except Exception as exc:
        print(f"Error analysing {name}: {exc}")

results.sort(key=lambda item: item.get("score", 0), reverse=True)

print("Ranking by rating:")
for index, app in enumerate(results, start=1):
    print(f"{index}. {app['name']}: {app.get('score', 'N/A')} stars")
```

--------------------------------

### Find Better Alternatives Example

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Identify apps with higher ratings than a given app by comparing scores of similar apps. Sort the results to show the best alternatives first.

```python
app_id = "com.example.app"
my_app = scraper.app_get_field(app_id, "score")
similar = scraper.similar_get_fields(app_id, ["title", "score", "url"], count=50)

# Find apps with higher ratings
better_apps = [app for app in similar if app['score'] and app['score'] > my_app]
better_apps.sort(key=lambda x: x['score'], reverse=True)

print(f"Apps better than {app_id} ({my_app}★):")
for app in better_apps[:10]:
    print(f"- {app['title']}: {app['score']}★")
```

--------------------------------

### developer_analyze

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/DEVELOPER_METHODS.md

Returns all apps from a developer as a list of dictionaries. Useful for getting a comprehensive overview of a developer's published applications.

```APIDOC
## developer_analyze(dev_id, count=100, lang='en', country='us')

### Description
Returns all apps from a developer as a list of dictionaries.

### Parameters
#### Path Parameters
- **dev_id** (str) - Required - Developer ID.
- **count** (int) - Optional - Maximum number of apps to return (default: 100).
- **lang** (str) - Optional - Language code (default: 'en').
- **country** (str) - Optional - Country code (default: 'us').

### Request Example
```python
apps = scraper.developer_analyze("5700313618786177705", count=50)
```

### Response
#### Success Response (200)
- Returns a list of dictionaries, where each dictionary represents an app and contains fields like 'appId', 'title', 'score', etc.

#### Response Example
```json
[
  {"appId": "...", "title": "...", "score": 4.5, ...},
  ...
]
```
```

--------------------------------

### Import and Initialize GPlayScraper

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Import the GPlayScraper class and create an instance. Networking is handled internally.

```python
from gplay_scraper import GPlayScraper

# Networking is handled internally
scraper = GPlayScraper()
```

--------------------------------

### Suggest Methods: Analyze

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/docs/quickstart.md

Gets search suggestions and autocomplete terms for a given query using analyze. Returns a list of suggestions.

```python
suggestions = scraper.suggest_analyze("fitness", count=5, lang="en", country="us")
print(suggestions)
```

--------------------------------

### Get Specific Field from Similar Apps

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SIMILAR_METHODS.md

Use `similar_get_field` to retrieve a single, specified field (e.g., 'title') from all similar apps.

```python
titles = scraper.similar_get_field("com.whatsapp", "title")
# Returns: ['App 1', 'App 2', 'App 3', ...]
```

--------------------------------

### suggest_analyze: Get Simple Search Suggestions

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Retrieves a list of search suggestions for a given term. Useful for basic keyword discovery.

```python
suggestions = scraper.suggest_analyze("video", count=5)
# Returns: ['video player', 'video editor', 'video downloader', 'video maker', 'video call']
```

--------------------------------

### Formatting Tip: Presenting Review Data

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/REVIEWS_METHODS.md

Demonstrates iterating through fetched review data and printing formatted output, including user name, score, and content.

```python
reviews = scraper.reviews_get_fields("com.whatsapp", ["userName", "score", "content"], count=10)
for idx, review in enumerate(reviews, 1):
    print(f"{idx}. {review['userName']} — {review['score']}★")
    print(f"   {review['content']}")
```

--------------------------------

### Practical Example: Long-Tail Keywords

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README/SUGGEST_METHODS.md

Filters search suggestions to identify long-tail keywords, defined as those with three or more words. Useful for niche targeting.

```python
short_term = "vpn"
suggestions = scraper.suggest_analyze(short_term, count=10)

# Filter for long-tail (3+ words)
long_tail = [s for s in suggestions if len(s.split()) >= 3]

print(f"Long-tail keywords for '{short_term}':")
for keyword in long_tail:
    print(f"- {keyword}")
```

--------------------------------

### Compare Competitors Across Regions

Source: https://context7.com/elmissouri16/gplay-scraper/llms.txt

Demonstrates fetching similar app data for different countries. Use this to understand how competitors perform and are perceived in various markets.

```python
from gplay_scraper import GPlayScraper

scraper = GPlayScraper()
app_id = "com.whatsapp"

competitors_us = scraper.similar_get_fields(app_id, ["title", "score"], count=5, lang="en", country="us")
competitors_jp = scraper.similar_get_fields(app_id, ["title", "score"], count=5, lang="ja", country="jp")
```

--------------------------------

### Initialize GPlayScraper with Proxies

Source: https://github.com/elmissouri16/gplay-scraper/blob/main/README.md

Initialize the GPlayScraper with optional proxy configurations. Proxies can be set as a single string for both http/https or as a dictionary mapping schemes to proxy URLs. Proxies can also be updated or disabled at runtime.

```python
from gplay_scraper import GPlayScraper

# Initialize scraper
scraper = GPlayScraper()

# Route traffic through a proxy (string applies to both http/https)
scraper_with_proxy = GPlayScraper(proxies="http://127.0.0.1:8080")

# Or provide a mapping for different schemes
scraper_with_split_proxy = GPlayScraper(
    proxies={
        "http": "http://corp-proxy.local:8080",
        "https": "http://secure-proxy.local:8443",
    }
)

# Update proxy configuration at runtime
scraper_with_proxy.set_proxies(None)  # Disable proxy when no longer needed
```