{
  "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": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error, on every route. Branch on code and retryable rather than on the text; on a 5xx the text is generic. MCP tool errors carry the same fields in structuredContent, and as a JSON text block.",
        "properties": {
          "error": {
            "type": "string",
            "description": "What went wrong, in words. For a 400, what to change."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status, repeated in the body."
          },
          "code": {
            "type": "string",
            "description": "The kind of error, stable: invalid_input, unauthorized, insufficient_credits, forbidden, not_found, expired, quota_exceeded, cancelled, time_limit, temporarily_unavailable, posts_unavailable, store_unreachable, upstream_error, internal_error, tool_error. A platform may add its own; more may be added. Treat a code you do not recognise by its retryable flag."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether asking again can succeed."
          },
          "requestId": {
            "type": "string",
            "description": "This request’s id, also sent as the X-Request-Id header. Quote it when reporting a problem."
          },
          "missing": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "With invalid_input when the request's parameters are refused before the request runs: the parameters that were missing. Always present on those errors, empty when nothing was missing."
          }
        },
        "required": [
          "error",
          "code",
          "retryable",
          "requestId"
        ]
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key."
      }
    }
  },
  "paths": {
    "/search": {
      "post": {
        "operationId": "search",
        "tags": [
          "Search"
        ],
        "summary": "Search Google Play apps",
        "description": "Search the Google Play app catalog by keyword and get back matching apps with their package name, developer, rating, install count, price, and store URL. Filter by store country, locale, and price. Use it to turn an app name into the package ID the reviews endpoint needs, or to pull a whole category of competing apps in one call. Google itself caps a query at roughly 20–250 apps, so `maxResults: -1` returns everything Google is willing to give rather than an unlimited catalog dump. Billing is per page actually fetched — the response reports `pagesFetched`, and the default `maxResults` of 50 is served by a single page (1 credit).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "description": "Search term, as typed into Google Play search."
                  },
                  "country": {
                    "type": "string",
                    "description": "Two-letter store country code (e.g. us, gb, jp).",
                    "example": "us"
                  },
                  "language": {
                    "type": "string",
                    "description": "Store locale (e.g. en-US, de-DE).",
                    "example": "en-US"
                  },
                  "price": {
                    "type": "string",
                    "description": "Price filter: all, free, or paid.",
                    "example": "all"
                  },
                  "maxResults": {
                    "type": "integer",
                    "description": "Maximum apps to return. Pass -1 to follow pagination until Google stops returning results. Billed per page actually fetched (see `pagesFetched`).",
                    "example": "50"
                  },
                  "resultsPerPage": {
                    "type": "integer",
                    "description": "Apps requested per pagination call (1-100).",
                    "example": "100"
                  },
                  "delayMs": {
                    "type": "integer",
                    "description": "Delay in milliseconds between pagination requests.",
                    "example": "1000"
                  },
                  "timeoutMs": {
                    "type": "integer",
                    "description": "Timeout in milliseconds for each Google Play request.",
                    "example": "30000"
                  },
                  "format": {
                    "type": "string",
                    "description": "json or markdown, in any case; any other value is a 400. Over MCP, markdown returns the result rendered as text; the REST API accepts it and returns JSON.",
                    "example": "json"
                  }
                },
                "additionalProperties": false,
                "required": [
                  "query"
                ]
              },
              "examples": {
                "default": {
                  "value": {
                    "query": "habit tracker",
                    "country": "gb",
                    "language": "en-GB",
                    "price": "free",
                    "maxResults": 50
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string",
                      "description": "The search term that was run."
                    },
                    "country": {
                      "type": "string",
                      "description": "Store country the results came from."
                    },
                    "language": {
                      "type": "string",
                      "description": "Store locale the results came from."
                    },
                    "price": {
                      "type": "string",
                      "description": "Price filter applied: all, free, or paid."
                    },
                    "apps": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "properties": {
                          "appId": {
                            "type": "string",
                            "description": "Android package name — pass this to the reviews endpoint."
                          },
                          "title": {
                            "type": "string",
                            "description": "App title as listed on the store."
                          },
                          "url": {
                            "type": "string",
                            "description": "Google Play listing URL."
                          },
                          "icon": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "App icon URL."
                          },
                          "developer": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Developer name."
                          },
                          "developerId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Developer ID. Only present for paginated results and the exact-match card."
                          },
                          "summary": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Plain-text one-liner, trimmed to 300 characters."
                          },
                          "score": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "description": "Average star rating from 0 to 5."
                          },
                          "scoreText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Rating as Google renders it (e.g. \"4.8\")."
                          },
                          "price": {
                            "type": "number",
                            "description": "Price in the listed currency; 0 for free apps."
                          },
                          "priceText": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Formatted price. Null for free apps."
                          },
                          "currency": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Currency code for the price."
                          },
                          "free": {
                            "type": "boolean",
                            "description": "Whether the app is free."
                          },
                          "installs": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Install count as Google renders it (e.g. \"5,000,000+\"). Only present for first-page results."
                          },
                          "genre": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Store category. Only present for first-page results."
                          },
                          "contentRating": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Content rating. Only present for first-page results."
                          },
                          "position": {
                            "type": "number",
                            "description": "One-based rank within the result set."
                          },
                          "topResult": {
                            "type": "boolean",
                            "description": "Whether Google surfaced this app as the exact-match hero card."
                          }
                        }
                      },
                      "description": "Matching apps, in Google Play's own ranking order."
                    },
                    "appCount": {
                      "type": "number",
                      "description": "Number of apps returned."
                    },
                    "pagesFetched": {
                      "type": "number",
                      "description": "Number of pagination calls made."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "analysis": {
                      "type": "object",
                      "properties": {
                        "totalApps": {
                          "type": "number",
                          "description": "Total apps included in the analysis."
                        },
                        "averageScore": {
                          "type": "number",
                          "description": "Average rating across the returned apps."
                        },
                        "freeApps": {
                          "type": "number",
                          "description": "How many of the returned apps are free."
                        },
                        "paidApps": {
                          "type": "number",
                          "description": "How many of the returned apps are paid."
                        },
                        "topDevelopers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "properties": {
                              "developer": {
                                "type": "string",
                                "description": "Developer name."
                              },
                              "appCount": {
                                "type": "number",
                                "description": "How many of the returned apps this developer publishes."
                              }
                            }
                          },
                          "description": "Developers with the most apps in the result set."
                        }
                      },
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "query": "habit tracker",
                      "country": "gb",
                      "language": "en-GB",
                      "price": "free",
                      "apps": [
                        {
                          "appId": "org.isoron.uhabits",
                          "title": "Loop Habit Tracker",
                          "url": "https://play.google.com/store/apps/details?id=org.isoron.uhabits",
                          "developer": "Álinson S Xavier",
                          "summary": "Track your habits and build a better life",
                          "score": 4.7767377,
                          "scoreText": "4.8",
                          "price": 0,
                          "priceText": null,
                          "currency": "USD",
                          "free": true,
                          "installs": "5,000,000+",
                          "genre": "Productivity",
                          "contentRating": "Everyone",
                          "position": 1,
                          "topResult": true
                        }
                      ],
                      "appCount": 1,
                      "pagesFetched": 1,
                      "scrapedAt": "2026-09-03T20:38:27.104Z",
                      "analysis": {
                        "totalApps": 1,
                        "averageScore": 4.78,
                        "freeApps": 1,
                        "paidApps": 0,
                        "topDevelopers": [
                          {
                            "developer": "Álinson S Xavier",
                            "appCount": 1
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/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. If you only know the app by name, run the search endpoint first and pass the `appId` it returns.",
        "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": "integer",
                    "description": "The page of results to start from."
                  },
                  "pages": {
                    "type": "integer",
                    "description": "How many pages of results to return."
                  },
                  "maxReviews": {
                    "type": "integer",
                    "description": "Maximum number of reviews to return."
                  },
                  "reviewsPerPage": {
                    "type": "integer",
                    "description": "Reviews requested per page (1-200)."
                  },
                  "sortBy": {
                    "type": "string",
                    "description": "Sort order: newest, mostRelevant, or rating."
                  },
                  "rating": {
                    "type": "integer",
                    "description": "Only return reviews with this star rating (1-5)."
                  },
                  "ratingFilter": {
                    "type": "array",
                    "items": {
                      "type": "number"
                    },
                    "description": "Only return reviews matching any listed star rating."
                  },
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only return reviews containing one or more keywords."
                  },
                  "endDate": {
                    "type": "string",
                    "description": "Stop at this review date (YYYY-MM-DD)."
                  },
                  "recentDays": {
                    "type": "integer",
                    "description": "Only return reviews from the most recent number of days."
                  },
                  "uniqueOnly": {
                    "type": "boolean",
                    "description": "Remove duplicate reviews."
                  },
                  "language": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only return reviews matching these language codes."
                  },
                  "deviceType": {
                    "type": "string",
                    "description": "Device filter: mobile, tablet, or chromebook."
                  },
                  "appVersion": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Only return reviews for these app versions."
                  },
                  "delayMs": {
                    "type": "integer",
                    "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": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true,
                        "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": "Day the review was posted, as YYYY-MM-DD (UTC)."
                          },
                          "body": {
                            "type": "string",
                            "description": "Full review text."
                          },
                          "appVersion": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "App version reviewed, when available."
                          },
                          "timestamp": {
                            "type": "integer",
                            "description": "When the review was posted, as Unix time in seconds (e.g. 1787047200). Multiply by 1000 for a JavaScript Date."
                          },
                          "language": {
                            "type": "string",
                            "description": "Detected review language."
                          }
                        }
                      },
                      "description": "Matching review records."
                    },
                    "reviewCount": {
                      "type": "number",
                      "description": "Number of reviews returned."
                    },
                    "pagesRequested": {
                      "type": "number",
                      "description": "Number of pages requested."
                    },
                    "scrapedAt": {
                      "type": "string",
                      "description": "ISO 8601 time the result was produced."
                    },
                    "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": true
                    }
                  },
                  "additionalProperties": true
                },
                "examples": {
                  "default": {
                    "value": {
                      "appId": "com.spotify.music",
                      "reviews": [
                        {
                          "reviewId": "review-id",
                          "rating": 5,
                          "reviewer": "Example user",
                          "date": "2026-08-18",
                          "body": "Great app",
                          "timestamp": 1787047200,
                          "language": "en"
                        }
                      ],
                      "reviewCount": 1,
                      "pagesRequested": 1,
                      "scrapedAt": "2026-08-18T10:00:01.000Z",
                      "analysis": {
                        "totalReviews": 1,
                        "averageRating": 5,
                        "ratingDistribution": {
                          "5": 1
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_input: the request needs fixing; error names the field.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "unauthorized: the API key is missing or not valid.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "insufficient_credits: no credits, trial or monthly allowance left.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "forbidden: this key or account is not allowed this request.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "quota_exceeded: a request-rate limit was reached.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "temporarily_unavailable, time_limit or (on a store route) store_unreachable: ask again (with time_limit, allow more time). Retryable.",
            "headers": {
              "X-Request-Id": {
                "description": "The request id, equal to requestId in the body.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  }
}