Rivioo

List the apps this Rivioo user saved: their own apps and competitors, each with store, app_id and default country (for Google Play the default country picks the review languages). Use it to look up an app the user names before calling rivioo_review_stats, rivioo_search_reviews or rivioo_get_reviews. Free; delivers no reviews.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "apps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "role": {
            "type": "string",
            "enum": [
              "own",
              "competitor"
            ]
          },
          "store": {
            "type": "string",
            "enum": [
              "ios",
              "android"
            ]
          },
          "app_id": {
            "type": "string"
          },
          "default_country": {
            "type": "string"
          },
          "developer": {
            "type": [
              "string",
              "null"
            ]
          },
          "store_url": {
            "type": "string"
          },
          "last_collected_at": {
            "description": "When reviews for the default country were last collected; null if never.",
            "type": [
              "string",
              "null"
            ]
          },
          "reviews_held": {
            "type": "number"
          }
        },
        "required": [
          "name",
          "role",
          "store",
          "app_id",
          "default_country",
          "developer",
          "store_url",
          "last_collected_at",
          "reviews_held"
        ],
        "additionalProperties": false
      }
    },
    "manage_url": {
      "type": "string"
    },
    "message": {
      "type": [
        "string",
        "null"
      ]
    },
    "collected_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean"
    },
    "quota": {
      "type": "object",
      "properties": {
        "monthly_allowance": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number",
          "description": "Reviews this account can still read for the first time this month."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "charged_this_call": {
          "type": "number",
          "description": "Reviews this call read for the first time in 30 days."
        },
        "free_rereads_this_call": {
          "type": "number",
          "description": "Reviews this call returned free because they were first read in the last 30 days."
        },
        "limit_reached": {
          "type": "boolean"
        },
        "message": {
          "description": "When set, tell the user.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "monthly_allowance",
        "used",
        "remaining",
        "resets_at",
        "charged_this_call",
        "free_rereads_this_call",
        "limit_reached",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "apps",
    "manage_url",
    "message",
    "collected_at",
    "cached",
    "quota"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Search the App Store and Google Play for apps by name in one storefront country (for Google Play the country later picks the review languages). Returns each match's app_id per store, developer, rating and store links. Use it for apps that are not in rivioo_my_apps; ask the user for the country if it is unknown. Omit store to search both stores. Free; delivers no reviews.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 100,
      "description": "App name or keywords."
    },
    "country": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "Two-letter storefront country to search, such as us or gb."
    },
    "store": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ],
      "description": "'ios' for the App Store or 'android' for Google Play."
    }
  },
  "required": [
    "query",
    "country"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "developer": {
            "type": [
              "string",
              "null"
            ]
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "stores": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "app_id": {
            "type": "object",
            "properties": {
              "ios": {
                "type": "string"
              },
              "android": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "store_urls": {
            "type": "object",
            "properties": {
              "ios": {
                "type": "string"
              },
              "android": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "icon_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "on_watchlist": {
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "developer",
          "rating",
          "stores",
          "app_id",
          "store_urls",
          "icon_url",
          "on_watchlist"
        ],
        "additionalProperties": false
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "collected_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean"
    },
    "quota": {
      "type": "object",
      "properties": {
        "monthly_allowance": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number",
          "description": "Reviews this account can still read for the first time this month."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "charged_this_call": {
          "type": "number",
          "description": "Reviews this call read for the first time in 30 days."
        },
        "free_rereads_this_call": {
          "type": "number",
          "description": "Reviews this call returned free because they were first read in the last 30 days."
        },
        "limit_reached": {
          "type": "boolean"
        },
        "message": {
          "description": "When set, tell the user.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "monthly_allowance",
        "used",
        "remaining",
        "resets_at",
        "charged_this_call",
        "free_rereads_this_call",
        "limit_reached",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "query",
    "country",
    "results",
    "warnings",
    "collected_at",
    "cached",
    "quota"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Exact rating distribution for one app over a window: total reviews, average rating, reviews per star and developer replies, also by app version (newest first, then other and unknown) and by week (weeks start Monday, UTC). Counts are the reviews Rivioo holds in the window, not users or every review ever written. App Store results are per country. Google Play results are per language, from all countries: the country picks the languages (English plus its main language). Use it for ratings, versions and weekly trends, and before reading reviews to see when ratings changed. Free; returns no review text. Collects newer reviews automatically when held reviews are older than max_age_hours.

{
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ],
      "description": "'ios' for the App Store or 'android' for Google Play."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Numeric App Store id (such as 324684580) or Google Play package name (such as com.spotify.music), from rivioo_my_apps or rivioo_find_app."
    },
    "country": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "Two-letter storefront country such as us or gb. For the App Store it picks the country's reviews; for Google Play it picks the review languages (English plus the country's main language), read from all countries. Optional for saved apps, which use the user's default country."
    },
    "days": {
      "description": "Window of this many days ending now. Defaults to 30. Use posted_from instead for exact dates.",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    },
    "posted_from": {
      "description": "Window start, inclusive, in UTC unless an offset is given. Use instead of days.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "posted_before": {
      "description": "Window end, exclusive. Defaults to now.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "app_version": {
      "description": "Only reviews of this exact app version.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_age_hours": {
      "default": 24,
      "description": "Reuse reviews collected within this many hours; older data is collected again automatically (newest reviews only). Default 24.",
      "type": "integer",
      "minimum": 1,
      "maximum": 720
    }
  },
  "required": [
    "store",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "notes": {
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Short facts about this result: what the reviews cover, whether the sample is small, what the counts mean and how reviews are identified."
    },
    "app": {
      "type": "object",
      "properties": {
        "store": {
          "type": "string",
          "enum": [
            "ios",
            "android"
          ]
        },
        "app_id": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "description": "The App Store country read, or for Google Play the country that picked the languages."
        },
        "country_source": {
          "type": "string",
          "enum": [
            "requested",
            "saved_default"
          ]
        },
        "label": {
          "type": "string",
          "description": "What these reviews cover, to name in answers: an App Store country, or Google Play languages from all countries."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages read. Null for the App Store, which is read by country."
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "on_watchlist": {
          "type": "boolean"
        },
        "role": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "own",
                "competitor"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "store_url": {
          "type": "string"
        },
        "app_reviews_url": {
          "type": "string",
          "description": "The app's reviews page in the store. Not a link to any single review."
        }
      },
      "required": [
        "store",
        "app_id",
        "country",
        "country_source",
        "label",
        "languages",
        "name",
        "on_watchlist",
        "role",
        "store_url",
        "app_reviews_url"
      ],
      "additionalProperties": false
    },
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      },
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "fresh",
        "cached",
        "collecting",
        "stale",
        "collection_failed"
      ],
      "description": "fresh: collected during this call. cached: held reviews within max_age_hours. collecting: a collection is still running and results are partial. stale: older than max_age_hours. collection_failed: the latest collection failed."
    },
    "collected_at": {
      "description": "When the held reviews were last collected, UTC.",
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean",
      "description": "true when the results come from reviews collected before this call."
    },
    "max_age_hours": {
      "type": "number"
    },
    "collection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "job_id": {
              "type": "string"
            },
            "state": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "completed",
                "failed"
              ]
            },
            "progress": {
              "type": "number"
            },
            "step": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "job_id",
            "state",
            "progress",
            "step"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage": {
      "type": "object",
      "properties": {
        "reviews_held": {
          "type": "number",
          "description": "Reviews Rivioo holds for this App Store country or these Google Play languages, all dates."
        },
        "held_from": {
          "type": [
            "string",
            "null"
          ]
        },
        "held_to": {
          "type": [
            "string",
            "null"
          ]
        },
        "contiguous_from": {
          "description": "Rivioo holds every review posted after this time, up to collected_at.",
          "type": [
            "string",
            "null"
          ]
        },
        "window_covered": {
          "type": "boolean",
          "description": "true when the held reviews cover the whole window without gaps."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages covered. Null for the App Store."
        }
      },
      "required": [
        "reviews_held",
        "held_from",
        "held_to",
        "contiguous_from",
        "window_covered",
        "languages"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "reviews": {
          "type": "number"
        },
        "average_rating": {
          "type": [
            "number",
            "null"
          ]
        },
        "ratings": {
          "type": "object",
          "properties": {
            "1": {
              "type": "number"
            },
            "2": {
              "type": "number"
            },
            "3": {
              "type": "number"
            },
            "4": {
              "type": "number"
            },
            "5": {
              "type": "number"
            }
          },
          "required": [
            "1",
            "2",
            "3",
            "4",
            "5"
          ],
          "additionalProperties": false
        },
        "with_developer_reply": {
          "type": "number"
        }
      },
      "required": [
        "reviews",
        "average_rating",
        "ratings",
        "with_developer_reply"
      ],
      "additionalProperties": false
    },
    "by_app_version": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "app_version": {
            "type": "string",
            "description": "Version string, 'other' for versions beyond the newest 15, or 'unknown' when the store gave none."
          },
          "versions": {
            "type": "number"
          },
          "reviews": {
            "type": "number"
          },
          "average_rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "ratings": {
            "type": "object",
            "properties": {
              "1": {
                "type": "number"
              },
              "2": {
                "type": "number"
              },
              "3": {
                "type": "number"
              },
              "4": {
                "type": "number"
              },
              "5": {
                "type": "number"
              }
            },
            "required": [
              "1",
              "2",
              "3",
              "4",
              "5"
            ],
            "additionalProperties": false
          },
          "first_posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_posted_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "app_version",
          "reviews",
          "average_rating",
          "ratings",
          "first_posted_at",
          "last_posted_at"
        ],
        "additionalProperties": false
      }
    },
    "by_week": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "week_start": {
            "type": "string"
          },
          "reviews": {
            "type": "number"
          },
          "average_rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "ratings": {
            "type": "object",
            "properties": {
              "1": {
                "type": "number"
              },
              "2": {
                "type": "number"
              },
              "3": {
                "type": "number"
              },
              "4": {
                "type": "number"
              },
              "5": {
                "type": "number"
              }
            },
            "required": [
              "1",
              "2",
              "3",
              "4",
              "5"
            ],
            "additionalProperties": false
          },
          "partial": {
            "type": "boolean",
            "description": "The window covers only part of this week."
          }
        },
        "required": [
          "week_start",
          "reviews",
          "average_rating",
          "ratings",
          "partial"
        ],
        "additionalProperties": false
      }
    },
    "quota": {
      "type": "object",
      "properties": {
        "monthly_allowance": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number",
          "description": "Reviews this account can still read for the first time this month."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "charged_this_call": {
          "type": "number",
          "description": "Reviews this call read for the first time in 30 days."
        },
        "free_rereads_this_call": {
          "type": "number",
          "description": "Reviews this call returned free because they were first read in the last 30 days."
        },
        "limit_reached": {
          "type": "boolean"
        },
        "message": {
          "description": "When set, tell the user.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "monthly_allowance",
        "used",
        "remaining",
        "resets_at",
        "charged_this_call",
        "free_rereads_this_call",
        "limit_reached",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "notes",
    "app",
    "window",
    "status",
    "collected_at",
    "cached",
    "max_age_hours",
    "collection",
    "coverage",
    "warnings",
    "totals",
    "by_app_version",
    "by_week",
    "quota"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Exact counts of the reviews of one app that mention specific words, plus snippets with review IDs. It is the tool for "how many reviews mention X" questions and for sizing themes found while reading reviews with rivioo_get_reviews. App Store results are per country. Google Play results are per language, from all countries: the country picks the languages (English plus its main language). any_of matches reviews containing at least one term; all_of requires every term; both can be combined. Matching is literal and case-insensitive on word starts: "crash" finds crashes and crashed, "ad" does not find "bad". A term with spaces matches those words in sequence. Chinese, Japanese, Korean and Thai terms match anywhere. Terms are not translated, so reviews in another language match only terms in that language. Returns the reviews in the window, the matching reviews, counts per term and per star, and up to limit snippets newest first, each with review_id and url when the store has one. Counts are free; each snippet uses one review of quota the first time that review reaches this account in 30 days. Pass next_cursor with the same arguments for more snippets.

{
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ],
      "description": "'ios' for the App Store or 'android' for Google Play."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Numeric App Store id (such as 324684580) or Google Play package name (such as com.spotify.music), from rivioo_my_apps or rivioo_find_app."
    },
    "country": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "Two-letter storefront country such as us or gb. For the App Store it picks the country's reviews; for Google Play it picks the review languages (English plus the country's main language), read from all countries. Optional for saved apps, which use the user's default country."
    },
    "any_of": {
      "description": "Match reviews containing at least one of these terms, such as [\"crash\", \"freeze\"].",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "all_of": {
      "description": "Match only reviews containing every one of these terms.",
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "days": {
      "description": "Window of this many days ending now. Defaults to 30. Use posted_from instead for exact dates.",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    },
    "posted_from": {
      "description": "Window start, inclusive, in UTC unless an offset is given. Use instead of days.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "posted_before": {
      "description": "Window end, exclusive. Defaults to now.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "ratings": {
      "description": "Only these star ratings, such as [1, 2].",
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 5
      }
    },
    "app_version": {
      "description": "Only reviews of this exact app version.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "has_developer_reply": {
      "description": "true for reviews the developer replied to, false for reviews without a reply.",
      "type": "boolean"
    },
    "limit": {
      "default": 15,
      "description": "Snippets to return, newest first. Default 15.",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "cursor": {
      "description": "next_cursor from the previous call, with the same arguments, for the next page.",
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "max_age_hours": {
      "default": 24,
      "description": "Reuse reviews collected within this many hours; older data is collected again automatically (newest reviews only). Default 24.",
      "type": "integer",
      "minimum": 1,
      "maximum": 720
    }
  },
  "required": [
    "store",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "notes": {
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Short facts about this result: what the reviews cover, whether the sample is small, what the counts mean and how reviews are identified."
    },
    "app": {
      "type": "object",
      "properties": {
        "store": {
          "type": "string",
          "enum": [
            "ios",
            "android"
          ]
        },
        "app_id": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "description": "The App Store country read, or for Google Play the country that picked the languages."
        },
        "country_source": {
          "type": "string",
          "enum": [
            "requested",
            "saved_default"
          ]
        },
        "label": {
          "type": "string",
          "description": "What these reviews cover, to name in answers: an App Store country, or Google Play languages from all countries."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages read. Null for the App Store, which is read by country."
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "on_watchlist": {
          "type": "boolean"
        },
        "role": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "own",
                "competitor"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "store_url": {
          "type": "string"
        },
        "app_reviews_url": {
          "type": "string",
          "description": "The app's reviews page in the store. Not a link to any single review."
        }
      },
      "required": [
        "store",
        "app_id",
        "country",
        "country_source",
        "label",
        "languages",
        "name",
        "on_watchlist",
        "role",
        "store_url",
        "app_reviews_url"
      ],
      "additionalProperties": false
    },
    "window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      },
      "required": [
        "from",
        "to"
      ],
      "additionalProperties": false
    },
    "status": {
      "type": "string",
      "enum": [
        "fresh",
        "cached",
        "collecting",
        "stale",
        "collection_failed"
      ],
      "description": "fresh: collected during this call. cached: held reviews within max_age_hours. collecting: a collection is still running and results are partial. stale: older than max_age_hours. collection_failed: the latest collection failed."
    },
    "collected_at": {
      "description": "When the held reviews were last collected, UTC.",
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean",
      "description": "true when the results come from reviews collected before this call."
    },
    "max_age_hours": {
      "type": "number"
    },
    "collection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "job_id": {
              "type": "string"
            },
            "state": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "completed",
                "failed"
              ]
            },
            "progress": {
              "type": "number"
            },
            "step": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "job_id",
            "state",
            "progress",
            "step"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage": {
      "type": "object",
      "properties": {
        "reviews_held": {
          "type": "number",
          "description": "Reviews Rivioo holds for this App Store country or these Google Play languages, all dates."
        },
        "held_from": {
          "type": [
            "string",
            "null"
          ]
        },
        "held_to": {
          "type": [
            "string",
            "null"
          ]
        },
        "contiguous_from": {
          "description": "Rivioo holds every review posted after this time, up to collected_at.",
          "type": [
            "string",
            "null"
          ]
        },
        "window_covered": {
          "type": "boolean",
          "description": "true when the held reviews cover the whole window without gaps."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages covered. Null for the App Store."
        }
      },
      "required": [
        "reviews_held",
        "held_from",
        "held_to",
        "contiguous_from",
        "window_covered",
        "languages"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "query": {
      "type": "object",
      "properties": {
        "any_of": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "all_of": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "match": {
          "type": "string"
        }
      },
      "required": [
        "any_of",
        "all_of",
        "match"
      ],
      "additionalProperties": false
    },
    "reviews_in_window": {
      "type": "number",
      "description": "Reviews held in the window after filters, matching or not."
    },
    "total_matching_reviews": {
      "type": "number",
      "description": "Reviews in the window matching the terms and filters. Not users."
    },
    "term_counts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "term": {
            "type": "string"
          },
          "reviews": {
            "type": "number"
          }
        },
        "required": [
          "term",
          "reviews"
        ],
        "additionalProperties": false
      },
      "description": "Reviews in the window containing each term on its own."
    },
    "matching_by_rating": {
      "type": "object",
      "properties": {
        "1": {
          "type": "number"
        },
        "2": {
          "type": "number"
        },
        "3": {
          "type": "number"
        },
        "4": {
          "type": "number"
        },
        "5": {
          "type": "number"
        }
      },
      "required": [
        "1",
        "2",
        "3",
        "4",
        "5"
      ],
      "additionalProperties": false
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "review_id": {
            "type": "string"
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "app_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "snippet": {
            "type": "string"
          },
          "matched_terms": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "description": "Link to this review. Null for App Store reviews, which have no per-review link.",
            "type": [
              "string",
              "null"
            ]
          },
          "has_developer_reply": {
            "type": "boolean"
          }
        },
        "required": [
          "review_id",
          "rating",
          "posted_at",
          "app_version",
          "snippet",
          "matched_terms",
          "url",
          "has_developer_reply"
        ],
        "additionalProperties": false
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "quota": {
      "type": "object",
      "properties": {
        "monthly_allowance": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number",
          "description": "Reviews this account can still read for the first time this month."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "charged_this_call": {
          "type": "number",
          "description": "Reviews this call read for the first time in 30 days."
        },
        "free_rereads_this_call": {
          "type": "number",
          "description": "Reviews this call returned free because they were first read in the last 30 days."
        },
        "limit_reached": {
          "type": "boolean"
        },
        "message": {
          "description": "When set, tell the user.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "monthly_allowance",
        "used",
        "remaining",
        "resets_at",
        "charged_this_call",
        "free_rereads_this_call",
        "limit_reached",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "notes",
    "app",
    "window",
    "status",
    "collected_at",
    "cached",
    "max_age_hours",
    "collection",
    "coverage",
    "warnings",
    "query",
    "reviews_in_window",
    "total_matching_reviews",
    "term_counts",
    "matching_by_rating",
    "results",
    "next_cursor",
    "quota"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Returns a page of full reviews of one app: reviews, not counts. To count how many reviews mention a theme, use rivioo_search_reviews. Every review has a review_id, and a url when the store has one (App Store reviews have no per-review link), to cite when quoting. App Store results are per country. Google Play results are per language, from all countries: the country picks the languages (English plus its main language). Pass review_ids (from rivioo_search_reviews) to read those reviews, or a window with filters to read reviews newest first. response_format concise returns id, rating, date, version, title, body and url; detailed adds language and developer reply. Each review uses one review of quota the first time it reaches this account in 30 days; reading it again in that time is free. Pass next_cursor with the same arguments for the next page.

{
  "type": "object",
  "properties": {
    "store": {
      "type": "string",
      "enum": [
        "ios",
        "android"
      ],
      "description": "'ios' for the App Store or 'android' for Google Play."
    },
    "app_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Numeric App Store id (such as 324684580) or Google Play package name (such as com.spotify.music), from rivioo_my_apps or rivioo_find_app."
    },
    "country": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "Two-letter storefront country such as us or gb. For the App Store it picks the country's reviews; for Google Play it picks the review languages (English plus the country's main language), read from all countries. Optional for saved apps, which use the user's default country."
    },
    "review_ids": {
      "description": "Read exactly these reviews. Window and filters are ignored.",
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      }
    },
    "days": {
      "description": "Window of this many days ending now. Defaults to 30. Use posted_from instead for exact dates.",
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    },
    "posted_from": {
      "description": "Window start, inclusive, in UTC unless an offset is given. Use instead of days.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "posted_before": {
      "description": "Window end, exclusive. Defaults to now.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,6})?)?(Z|[+-]\\d{2}:?\\d{2}))?$"
    },
    "ratings": {
      "description": "Only these star ratings, such as [1, 2].",
      "minItems": 1,
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 5
      }
    },
    "app_version": {
      "description": "Only reviews of this exact app version.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "has_developer_reply": {
      "description": "true for reviews the developer replied to, false for reviews without a reply.",
      "type": "boolean"
    },
    "limit": {
      "default": 25,
      "description": "Reviews per page, newest first. Default 25.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "response_format": {
      "default": "concise",
      "type": "string",
      "enum": [
        "concise",
        "detailed"
      ]
    },
    "cursor": {
      "description": "next_cursor from the previous call, with the same arguments, for the next page.",
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "max_age_hours": {
      "default": 24,
      "description": "Reuse reviews collected within this many hours; older data is collected again automatically (newest reviews only). Default 24.",
      "type": "integer",
      "minimum": 1,
      "maximum": 720
    }
  },
  "required": [
    "store",
    "app_id"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "notes": {
      "maxItems": 4,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Short facts about this result: what the reviews cover, whether the sample is small, what the counts mean and how reviews are identified."
    },
    "app": {
      "type": "object",
      "properties": {
        "store": {
          "type": "string",
          "enum": [
            "ios",
            "android"
          ]
        },
        "app_id": {
          "type": "string"
        },
        "country": {
          "type": "string",
          "description": "The App Store country read, or for Google Play the country that picked the languages."
        },
        "country_source": {
          "type": "string",
          "enum": [
            "requested",
            "saved_default"
          ]
        },
        "label": {
          "type": "string",
          "description": "What these reviews cover, to name in answers: an App Store country, or Google Play languages from all countries."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages read. Null for the App Store, which is read by country."
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "on_watchlist": {
          "type": "boolean"
        },
        "role": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "own",
                "competitor"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "store_url": {
          "type": "string"
        },
        "app_reviews_url": {
          "type": "string",
          "description": "The app's reviews page in the store. Not a link to any single review."
        }
      },
      "required": [
        "store",
        "app_id",
        "country",
        "country_source",
        "label",
        "languages",
        "name",
        "on_watchlist",
        "role",
        "store_url",
        "app_reviews_url"
      ],
      "additionalProperties": false
    },
    "window": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "from": {
              "type": "string"
            },
            "to": {
              "type": "string"
            }
          },
          "required": [
            "from",
            "to"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "fresh",
        "cached",
        "collecting",
        "stale",
        "collection_failed"
      ],
      "description": "fresh: collected during this call. cached: held reviews within max_age_hours. collecting: a collection is still running and results are partial. stale: older than max_age_hours. collection_failed: the latest collection failed."
    },
    "collected_at": {
      "description": "When the held reviews were last collected, UTC.",
      "type": [
        "string",
        "null"
      ]
    },
    "cached": {
      "type": "boolean",
      "description": "true when the results come from reviews collected before this call."
    },
    "max_age_hours": {
      "type": "number"
    },
    "collection": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "job_id": {
              "type": "string"
            },
            "state": {
              "type": "string",
              "enum": [
                "queued",
                "running",
                "completed",
                "failed"
              ]
            },
            "progress": {
              "type": "number"
            },
            "step": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "required": [
            "job_id",
            "state",
            "progress",
            "step"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage": {
      "type": "object",
      "properties": {
        "reviews_held": {
          "type": "number",
          "description": "Reviews Rivioo holds for this App Store country or these Google Play languages, all dates."
        },
        "held_from": {
          "type": [
            "string",
            "null"
          ]
        },
        "held_to": {
          "type": [
            "string",
            "null"
          ]
        },
        "contiguous_from": {
          "description": "Rivioo holds every review posted after this time, up to collected_at.",
          "type": [
            "string",
            "null"
          ]
        },
        "window_covered": {
          "type": "boolean",
          "description": "true when the held reviews cover the whole window without gaps."
        },
        "languages": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "null"
            }
          ],
          "description": "Google Play review languages covered. Null for the App Store."
        }
      },
      "required": [
        "reviews_held",
        "held_from",
        "held_to",
        "contiguous_from",
        "window_covered",
        "languages"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "total_matching_reviews": {
      "type": "number",
      "description": "Reviews in the window matching the filters, or the IDs found."
    },
    "reviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "review_id": {
            "type": "string"
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "posted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "app_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "body": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "description": "Link to this review. Null for App Store reviews, which have no per-review link.",
            "type": [
              "string",
              "null"
            ]
          },
          "lang": {
            "type": [
              "string",
              "null"
            ]
          },
          "developer_reply": {
            "type": [
              "string",
              "null"
            ]
          },
          "developer_reply_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "description": "App Store country of the review. Null for Google Play, whose reviews are per language.",
            "type": [
              "string",
              "null"
            ]
          },
          "store": {
            "type": "string"
          }
        },
        "required": [
          "review_id",
          "rating",
          "posted_at",
          "app_version",
          "title",
          "body",
          "url"
        ],
        "additionalProperties": false
      }
    },
    "not_found_review_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "not_shown_review_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "quota": {
      "type": "object",
      "properties": {
        "monthly_allowance": {
          "type": "number"
        },
        "used": {
          "type": "number"
        },
        "remaining": {
          "type": "number",
          "description": "Reviews this account can still read for the first time this month."
        },
        "resets_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "charged_this_call": {
          "type": "number",
          "description": "Reviews this call read for the first time in 30 days."
        },
        "free_rereads_this_call": {
          "type": "number",
          "description": "Reviews this call returned free because they were first read in the last 30 days."
        },
        "limit_reached": {
          "type": "boolean"
        },
        "message": {
          "description": "When set, tell the user.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "monthly_allowance",
        "used",
        "remaining",
        "resets_at",
        "charged_this_call",
        "free_rereads_this_call",
        "limit_reached",
        "message"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "notes",
    "app",
    "window",
    "status",
    "collected_at",
    "cached",
    "max_age_hours",
    "collection",
    "coverage",
    "warnings",
    "total_matching_reviews",
    "reviews",
    "not_found_review_ids",
    "not_shown_review_ids",
    "next_cursor",
    "quota"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}