> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/documentation/guides/what-is-review-monitoring/app-store-data-guide.md). # App Store Data Guide When you fetch app reviews with Pullbay, you get rich structured data for each review. This guide explains every field in the response, what each one means, how to use it, and real-world examples. Whether you're building a dashboard, analyzing sentiment, or filtering reviews by region, understanding your data is the foundation of smart review monitoring. ## The Complete App Store Review Object Here's a full annotated response with every field explained inline: ```json { "data": [ { "id": "review_abc123def456", "app_id": "284882215", "rating": 4, "title": "Great app but needs dark mode", "content": "I've been using this app for 2 years. It's excellent for productivity, but I really wish there was a dark mode option. My eyes hurt after using it in the evening. Otherwise, perfect!", "author": "ProductiveUser42", "date": "2024-01-15T14:32:00Z", "version": "10.2.1", "helpful_count": 127, }, { "id": "review_xyz789abc123", "app_id": "284882215", "rating": 1, "title": "Crashes on startup", "content": "Updated to the latest version yesterday and now it won't even open. Just crashes immediately. Please fix ASAP!", "author": "FrustratedUser88", "date": "2024-01-16T09:15:00Z", "version": "10.3.0", "helpful_count": 342, }, { "id": "review_dev_response_001", "app_id": "284882215", "rating": 3, "title": "Good but expensive", "content": "The app works well, but the subscription cost is way too high compared to competitors.", "author": "BudgetConsciousUser", "date": "2024-01-14T16:45:00Z", "version": "10.2.0", "helpful_count": 89, } ], "pagination": { "next_cursor": "cursor_next_page_abc123", "has_more": true }, "meta": { "credits_used": 1, "request_id": "req_1705419300_abc123" } } ``` ## Field Reference and Use Cases ### Core Identification Fields #### **id** (string) Unique identifier for this review. It never changes and is globally unique across all reviews in Pullbay's system. * **Data type**: String (format: `review_` followed by alphanumeric characters) * **Example**: `review_abc123def456` * **Use cases**: * Primary key for storing reviews in your database * Idempotency: Use this to avoid inserting duplicate reviews when polling * Reference in your internal systems (link reviews to tickets, alerts, etc.) #### **app\_id** (string) The Apple App Store ID for the app being reviewed. This is the unique identifier of the app in Apple's system. * **Data type**: String (numeric App Store ID) * **Example**: `284882215` (X/Twitter on iOS) * **Use cases**: * Filter reviews by app if you're monitoring multiple apps * Join with your internal app database to add context (e.g., app name, team owner) * Include in dashboards and reports to clarify which app is being reviewed *** ### Review Content Fields #### **rating** (integer) Star rating: 1 (lowest) to 5 (highest). * **Data type**: Integer (1–5) * **Example**: `4`, `1`, `5` * **Use cases**: * Compute average rating: `sum(r['rating']) / len(reviews)` * Distribution analysis: Count reviews by star level * Filter low ratings: `[r for r in reviews if r['rating'] <= 2]` * Trend detection: Compare average rating this week vs. last week * Sentiment proxy: Lower ratings often indicate bugs or friction #### **title** (string) The review headline. Usually short (2–20 words), often summarizes the main feedback. * **Data type**: String (up to \~100 characters) * **Example**: `"Great app but needs dark mode"`, `"Crashes on startup"` * **Use cases**: * Keyword extraction: Parse titles to identify common topics ("dark mode", "crash", "expensive") * First-pass triage: Titles often communicate the main issue (read title before full review body) * Sentiment analysis: Apply NLP to detect positive/negative language * Search: Index titles to find reviews about specific issues #### **content** (string) The full review text. Usually longer (1–500+ words), contains detailed feedback, bug descriptions, feature requests, and context. * **Data type**: String (variable length, up to several paragraphs) * **Example**: `"I've been using this app for 2 years. It's excellent for productivity, but I really wish..."` * **Use cases**: * Bug detection: Search for keywords like "crash", "freeze", "won't load", "error" * Feature requests: Parse text for "please add", "would love", "feature request" * Detailed analysis: Read full content for context that title doesn't provide * Customer support: Use content text to understand user's exact problem * Sentiment analysis: Train ML models or use APIs to gauge overall sentiment #### **author** (string) The App Store username of the reviewer (pseudonymous; not real name). * **Data type**: String * **Example**: `"ProductiveUser42"`, `"FrustratedUser88"` * **Use cases**: * Identify repeat reviewers: Track if same user reviews multiple times (often indicates power user or chronic complainer) * Spot fake reviews: Flag accounts with suspicious patterns (e.g., many 1-star reviews posted in succession) * User segments: Separate feedback from different reviewer types * Engagement: Respond to helpful users and build community *** ### Review Metadata Fields #### **date** (string, ISO 8601 format) When the review was posted, in UTC timezone. * **Data type**: String (ISO 8601 format: `YYYY-MM-DDTHH:mm:ssZ`) * **Example**: `"2024-01-15T14:32:00Z"` * **Use cases**: * Timeline correlation: Link review spikes to app releases, marketing campaigns, or outages * Recency filtering: Focus on recent reviews for real-time monitoring * Trend analysis: Group reviews by week, month, or release cycle * Regression detection: If average rating drops on a specific date, investigate what changed in the app * Export filtering: "Give me all reviews from the last 7 days" #### **country** (string, ISO 3166-1 alpha-2 code) Two-letter country code where the reviewer is located (based on App Store regional store). * **Data type**: String (2-letter country code, uppercase) * **Examples**: `"US"`, `"GB"`, `"DE"`, `"JP"`, `"AU"`, `"FR"`, `"IN"` * **Use cases**: * Regional analysis: Compare feedback between US, UK, India, Japan * Localization QA: Spot regional bugs or language-related issues * Launch strategy: Monitor reviews in new markets you just expanded to * Regulation compliance: Filter reviews from specific countries for compliance (e.g., GDPR) * Feature parity: Identify if certain features are available or problematic in specific regions * Market research: Understand how different regions perceive your app #### **version** (string, semantic versioning format) App version when the review was submitted (e.g., `"10.2.1"`, `"1.0.0"`). * **Data type**: String (semantic version: `major.minor.patch`) * **Example**: `"10.2.1"`, `"10.3.0"`, `"9.1.2"` * **Use cases**: * Release correlation: If reviews for v10.3.0 have lower average rating, that version likely has an issue * Regression detection: Compare v10.2.1 reviews to v10.3.0 reviews to pinpoint what broke * User adoption tracking: See which versions users are running * Support prioritization: Older versions may not get fixes, but newer versions are important to stabilize * A/B testing: If you deploy variants, track reviews per variant #### **helpful\_count** (integer) Number of App Store users who marked this review as "helpful". * **Data type**: Integer (0 or greater) * **Example**: `127`, `342`, `0` * **Use cases**: * Prioritization: Read high-helpful reviews first (they resonate with many users) * Impact estimation: Reviews with 100+ helpful votes likely describe a widespread issue * Consensus identification: Multiple 1-star reviews with high helpful counts signal a real problem * Dismiss outliers: Reviews with 0 helpful votes might be spam or edge cases *** ### Review Prioritization Use `helpful_count` to prioritize which reviews to address first. Reviews with higher helpful counts represent issues that resonate most broadly with your user base: * **Data type**: Integer * **Example**: `342` (342 users found this review helpful) * **Use cases**: * Prioritize: Focus on reviews with high helpful counts — these represent widespread user sentiment * Quality gate: Filter out spam by requiring `helpful_count >= 1` * Trending: Track which reviews are gaining traction over time *** ## How to Filter and Query Reviews ### Filter by Rating Get only negative reviews (1–2 stars): ```python low_reviews = [r for r in reviews if r['rating'] <= 2] print(f"Negative reviews: {len(low_reviews)}") ``` Get only positive reviews (4–5 stars): ```python high_reviews = [r for r in reviews if r['rating'] >= 4] print(f"Positive reviews: {len(high_reviews)}") ``` ### Filter by Country Country filtering is done at the API request level using the `country` parameter. Reviews from a specific country are fetched by passing `country` as a request parameter — the API returns reviews for that country's App Store: ```bash # Get reviews from the US App Store (default) curl "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215&country=us" \ -H "Authorization: Bearer YOUR_API_KEY" # Get reviews from the Japan App Store curl "https://api.pullbay.com/v1/app-store/reviews?app_id=284882215&country=jp" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python # Fetch reviews from multiple countries with separate requests countries = ["us", "gb", "de", "fr"] all_country_reviews = {} for country in countries: response = requests.get( "https://api.pullbay.com/v1/app-store/reviews", headers={"Authorization": f"Bearer {API_KEY}"}, params={"app_id": "284882215", "country": country} ) all_country_reviews[country] = response.json()["data"] ``` ### Filter by Version Identify issues in a specific app version: ```python v10_3_0_reviews = [r for r in reviews if r['version'] == '10.3.0'] avg_rating = sum(r['rating'] for r in v10_3_0_reviews) / len(v10_3_0_reviews) print(f"v10.3.0 average rating: {avg_rating:.2f}") ``` Compare two versions: ```python def compare_versions(reviews, v1, v2): r1 = [r for r in reviews if r['version'] == v1] r2 = [r for r in reviews if r['version'] == v2] avg1 = sum(r['rating'] for r in r1) / len(r1) if r1 else 0 avg2 = sum(r['rating'] for r in r2) / len(r2) if r2 else 0 print(f"{v1}: {avg1:.2f}⭐ ({len(r1)} reviews)") print(f"{v2}: {avg2:.2f}⭐ ({len(r2)} reviews)") ``` ### Filter by Keyword Find reviews mentioning specific issues: ```python def find_reviews_with_keyword(reviews, keyword): keyword_lower = keyword.lower() return [r for r in reviews if keyword_lower in r['title'].lower() or keyword_lower in r['content'].lower()] crash_reviews = find_reviews_with_keyword(reviews, "crash") dark_mode_requests = find_reviews_with_keyword(reviews, "dark mode") print(f"Crash-related reviews: {len(crash_reviews)}") print(f"Dark mode requests: {len(dark_mode_requests)}") ``` ### Filter by Helpful Count Find impactful negative reviews that many users agree with: ```python impactful_negative = [r for r in reviews if r.get('helpful_count', 0) >= 10 and r['rating'] <= 2] print(f"High-impact negative reviews: {len(impactful_negative)}") for review in impactful_negative: print(f" {review['rating']}⭐ ({review['helpful_count']} helpful) — {review['title']}") ``` *** ## Pagination Explained Pullbay returns reviews in paginated batches to handle large datasets efficiently. ### Standard Pagination (Manual) Use `/v1/app-store/reviews` for manual pagination: ```python import requests api_key = "YOUR_API_KEY" app_id = "284882215" cursor = None all_reviews = [] headers = {"Authorization": f"Bearer {api_key}"} while True: params = { "app_id": app_id, "country": "us", "limit": 100 } # Add cursor for next page if cursor: params["cursor"] = cursor response = requests.get( "https://api.pullbay.com/v1/app-store/reviews", headers=headers, params=params ) data = response.json() all_reviews.extend(data['data']) print(f"Fetched {len(data['data'])} reviews. Total so far: {len(all_reviews)}") # Check if more pages exist if not data['pagination']['has_more']: break # Get next cursor cursor = data['pagination']['next_cursor'] print(f"Final total: {len(all_reviews)}") ``` ### Auto-Pagination (Automatic) Use `/v1/app-store/reviews/all` to fetch all pages automatically in one call: ```python import requests api_key = "YOUR_API_KEY" headers = {"Authorization": f"Bearer {api_key}"} params = { "app_id": "284882215", "country": "us" } response = requests.get( "https://api.pullbay.com/v1/app-store/reviews/all", headers=headers, params=params ) data = response.json() all_reviews = data['data'] print(f"Total reviews: {len(all_reviews)}") print(f"Credits used: {data['meta']['credits_used']}") ``` {% hint style="info" %} Use `/all` for batch exports (initial data load, weekly backups). Use manual pagination for real-time polling where you want to control page size and timing. {% endhint %} *** ## Data Freshness and Updates Review data is typically updated within **1–2 hours** of publication on the App Store. This lag reflects: * **App Store indexing time**: Apple takes time to index new reviews * **Pullbay refresh cycle**: We poll periodically and cache results * **Your polling frequency**: If you poll once per day, you'll see 24-hour-old data at best For most use cases (bug detection, trend monitoring, competitor analysis), 1–2 hour freshness is sufficient. If you need fresher data, poll more frequently (e.g., every 30 minutes), but this increases your API quota usage. *** ## Real-World Use Cases for Each Field | Field | Use Case | Example | | ------------------ | ------------------------------------------------- | -------------------------------------------------------- | | **id** | Avoid duplicate inserts; link to external tickets | "This review (id) relates to bug #1234" | | **app\_id** | Multi-app monitoring; join with your database | Filter reviews for App A vs. App B | | **rating** | Calculate average; detect rating drops | "Average dropped to 3.2⭐ after v10.3.0" | | **title** | Quick triage; keyword extraction | "Crashes on startup" → report to engineering | | **content** | Detailed analysis; sentiment; feature extraction | Find all feature requests; parse bug descriptions | | **author** | Identify power users; spot fake reviews | "User X has posted 50 1-star reviews" | | **date** | Timeline correlation; "what happened that day?" | "Rating spike on Jan 15 correlates with v10.2.1 release" | | **country** | Regional bugs; market research; compliance | "Germany has higher crash reports; localization issue?" | | **version** | Regression detection; release health | "v10.3.0 average rating: 2.1⭐ vs. v10.2.1: 4.3⭐" | | **helpful\_count** | Prioritize; measure impact | "Top 5 most-helpful reviews describe the same bug" | *** ## Common Questions About Review Data
How accurate is the review data? Review data comes directly from Apple's App Store and is normalized by Pullbay for consistency. The data is accurate as of the last refresh cycle (typically within 1–2 hours of publication). Occasionally, reviews are edited or deleted by users or Apple; Pullbay reflects the latest state.
Can I request reviews for a specific date range? The API doesn't offer date-range filters. Instead, fetch all reviews and filter client-side: ```python from datetime import datetime start_date = datetime.fromisoformat("2024-01-01T00:00:00Z") filtered = [r for r in reviews if datetime.fromisoformat(r['date']) >= start_date] ```
What if a review is edited or deleted? When a user edits a review, the updated text appears on the next fetch. When a review is deleted, it no longer appears in the API response. Pullbay doesn't track edit history or deletions—it always returns the current state.
Can I export all historical reviews? Yes, use the `/v1/app-store/reviews/all` endpoint to fetch all available reviews for an app. How many reviews are available depends on the app's history; some apps have years of reviews. We recommend storing results in your database so you have a persistent backup.
What's the difference between helpful_count and review quality? `helpful_count` is how many users found the review useful, but it's not a quality metric. A 1-star review with 200 helpful votes describes a real problem that many users experienced; a 5-star review with 0 helpful votes might be less impactful. Use helpful\_count to prioritize and identify consensus issues.
*** ## Key Takeaways * **Every field in the review object serves a purpose**: ratings, text content, metadata, and responses all inform different analyses * **Rating** tells you sentiment; **title/content** tell you what the issue is; **version** links to code; **country** reveals regional patterns * **Use pagination wisely**: Auto-pagination (`/all`) for bulk exports; manual pagination for real-time polling * **Filter strategically**: By rating (sentiment), country (region), version (regression), or keywords (specific issues) * **Developer responses** are important: Track what you've promised and follow through * **Data is typically fresh within 1–2 hours**, so polling every 30–60 minutes is reasonable for monitoring * **Store reviews in your database** for long-term analysis, trend detection, and compliance For API reference and code examples, see the [App Store Review API guide](broken://pages/8e5c461db88c0cabc7c858d9b307e6192e4e1ca3). For monitoring workflows, check the [Review Monitoring guide](broken://pages/d7638066cb7ad3f4115949205510111d0d2821ac). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pullbay.com/documentation/guides/what-is-review-monitoring/app-store-data-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.