{
  "openapi": "3.1.0",
  "info": {
    "title": "Google Play Store API",
    "version": "1.0.0",
    "description": "Google Play Store app reviews exposed through FetchLayer."
  },
  "servers": [
    {
      "url": "https://api.fetchlayer.dev/playstore"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/reviews": {
      "post": {
        "operationId": "reviews",
        "tags": [
          "Reviews"
        ],
        "summary": "Fetch app reviews",
        "description": "Fetch Google Play reviews using an app ID or listing URL. Supports pagination, sorting, rating and keyword filters, date windows, language, device type, and app version filters.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "appIdOrUrl": {
                    "type": "string",
                    "description": "Google Play package ID or full app listing URL."
                  },
                  "startPage": {
                    "type": "number",
                    "description": "Page number at which scraping starts."
                  },
                  "pages": {
                    "type": "number",
                    "description": "Number of pages to scrape."
                  },
                  "maxReviews": {
                    "type": "number",
                    "description": "Maximum number of reviews to return."
                  },
                  "reviewsPerPage": {
                    "type": "number",
                    "description": "Reviews requested per page (1-200)."
                  },
                  "sortBy": {
                    "type": "string",
                    "description": "Sort order: newest, mostRelevant, or rating."
                  },
                  "rating": {
                    "type": "number",
                    "description": "Only return reviews with this star rating (1-5)."
                  },
                  "ratingFilter": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Only return reviews matching any listed star rating."
                  },
                  "keywords": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Only return reviews containing one or more keywords."
                  },
                  "endDate": {
                    "type": "string",
                    "description": "Stop at this review date (YYYY-MM-DD)."
                  },
                  "recentDays": {
                    "type": "number",
                    "description": "Only return reviews from the most recent number of days."
                  },
                  "uniqueOnly": {
                    "type": "boolean",
                    "description": "Remove duplicate reviews."
                  },
                  "language": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Only return reviews matching these language codes."
                  },
                  "deviceType": {
                    "type": "string",
                    "description": "Device filter: mobile, tablet, or chromebook."
                  },
                  "appVersion": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Only return reviews for these app versions."
                  },
                  "delayMs": {
                    "type": "number",
                    "description": "Delay in milliseconds between page requests."
                  }
                },
                "additionalProperties": false,
                "required": [
                  "appIdOrUrl"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "appIdOrUrl": "com.spotify.music",
                    "pages": 1,
                    "reviewsPerPage": 20,
                    "sortBy": "newest"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "appId": {
                      "type": "string",
                      "description": "Google Play package ID."
                    },
                    "reviews": {
                      "type": "object",
                      "additionalProperties": true,
                      "description": "Matching review records.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "reviewId": {
                            "type": "string",
                            "description": "Unique review identifier."
                          },
                          "rating": {
                            "type": "number",
                            "description": "Star rating from 1 to 5."
                          },
                          "reviewer": {
                            "type": "string",
                            "description": "Reviewer display name."
                          },
                          "date": {
                            "type": "string",
                            "description": "Human-readable review date."
                          },
                          "body": {
                            "type": "string",
                            "description": "Full review text."
                          },
                          "appVersion": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "App version reviewed, when available."
                          },
                          "timestamp": {
                            "type": "string",
                            "description": "ISO 8601 review timestamp."
                          },
                          "language": {
                            "type": "string",
                            "description": "Detected review language."
                          }
                        },
                        "additionalProperties": false
                      }
                    },
                    "reviewCount": {
                      "type": "number",
                      "description": "Number of reviews returned."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 scrape completion time."
                    },
                    "analysis": {
                      "type": "object",
                      "properties": {
                        "totalReviews": {
                          "type": "number",
                          "description": "Total reviews included in the analysis."
                        },
                        "averageRating": {
                          "type": "number",
                          "description": "Average rating across returned reviews."
                        },
                        "ratingDistribution": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Counts grouped by star rating."
                        }
                      },
                      "additionalProperties": false
                    }
                  },
                  "additionalProperties": false
                },
                "examples": {
                  "default": {
                    "value": {
                      "appId": "com.spotify.music",
                      "reviews": [
                        {
                          "reviewId": "review-id",
                          "rating": 5,
                          "reviewer": "Example user",
                          "body": "Great app",
                          "timestamp": "2026-08-18T10:00:00.000Z",
                          "language": "en"
                        }
                      ],
                      "reviewCount": 1,
                      "pagesRequested": 1,
                      "scrapedAt": "2026-08-18T10:00:01.000Z",
                      "analysis": {
                        "totalReviews": 1,
                        "averageRating": 5,
                        "ratingDistribution": {
                          "5": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing Bearer token"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}