# Firefox Add-ons Reviews Parser (`genial_candlestand/firefox-addons-reviews-parser`) Actor

Fetches and normalizes public Firefox add-on ratings and reviews from Mozilla's v5 API. Export normalized ratings and reviews to JSON, CSV, Excel, or an API integration for repeatable monitoring and analysis.

- **URL**: https://apify.com/genial\_candlestand/firefox-addons-reviews-parser.md
- **Developed by:** [Flowo](https://apify.com/genial_candlestand) (community)
- **Categories:** E-commerce, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.50 / 1,000 review delivereds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Firefox Add-ons Reviews Parser

Fetch and normalize public Firefox add-on ratings and reviews from Mozilla’s v5 API. Provide add-on slugs or canonical public AMO add-on or reviews URLs, select the review limit and optional rating or written-text filters, and receive consistent records for analysis, monitoring, or integration.

Built for data teams, analytics engineers, intelligence platforms, and developers.

### Why use this Actor?

- Collect reviews for multiple Firefox add-ons in one run, with a separate limit of 1–1,000 matching reviews per add-on.
- Focus the dataset by selecting one or more star ratings and, when needed, excluding reviews without non-empty written text.
- Work with a normalized structure covering add-on and version identifiers, reviewer display name, score, body, creation time, review-state fields, and an optional structured developer reply.
- Use Mozilla’s top-level rating ID as the record identity, making the results suitable for repeatable review-monitoring and data-processing workflows.

### Use cases

- Create a bounded snapshot of currently available public ratings and reviews for selected Firefox add-ons.
- Export normalized review records to JSON or CSV for analysis in spreadsheets, databases, or data pipelines.
- Monitor written feedback at selected star levels to identify complaints, praise, and recurring product themes.
- Inspect a predictable review schema before integrating Firefox add-on feedback into an analytics or intelligence platform.

### How it works

1. Enter one or more add-on slugs or canonical addons.mozilla.org Firefox add-on or reviews URLs. Equivalent targets are normalized and collected once.
2. Set the maximum number of matching reviews to return for each add-on, from 1 to 1,000. The default is 100.
3. Optionally select any combination of one- through five-star ratings and enable the written-reviews-only filter. Leaving the ratings selection empty includes all star levels.
4. The Actor requests public rating records from Mozilla’s v5 ratings API, follows validated source-provided pagination, rechecks filters locally, and deduplicates records using Mozilla’s top-level rating ID.
5. Normalized reviews are written to the default Dataset, while a separate run summary is available from the default key-value store.

### Quick Start

1. Open the Actor in Apify Console and enter the input described below.
2. Click **Start** and wait for the run to finish.
3. Open the **Dataset** tab to preview or export the delivered records as JSON, CSV, XML, or Excel.

### Input Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `addons` | `array` of strings | Yes | — | One or more add-on slugs or canonical public AMO add-on or reviews URLs. Equivalent targets are normalized and deduplicated in first-seen order. |
| `maxItems` | `integer` | Yes | `100` | Maximum matching reviews to deliver for each add-on. Min: 1; max: 1,000. |
| `ratings` | `array` of strings | No | — | Unique star values `"1"` through `"5"`. Leave empty or omit to include every rating. |
| `onlyWithText` | `boolean` | Yes | `false` | When enabled, deliver only reviews whose body remains non-empty after whitespace trimming. |

#### Sample input

```json
{
  "addons": [
    "ublock-origin",
    "https://addons.mozilla.org/en-US/firefox/addon/darkreader/reviews/"
  ],
  "maxItems": 1,
  "ratings": ["1", "2"],
  "onlyWithText": false
}
```

### Output Data Format

Each successfully delivered entity is stored as one item in the default Dataset. Every top-level field below is present; nullable values such as review bodies, reviewer display names, and developer replies are represented as `null` when unavailable.

| Field | Observed type | Description |
| :--- | :--- | :--- |
| `id` | `integer` | Present in the verified candidate Dataset sample. |
| `addon` | `object` | Present in the verified candidate Dataset sample. |
| `reviewer` | `object` | Present in the verified candidate Dataset sample. |
| `version` | `object` | Present in the verified candidate Dataset sample. |
| `review` | `object` | Present in the verified candidate Dataset sample. |
| `developerReply` | `null` | Present in the verified candidate Dataset sample. |

#### Sample output

```json
[
  {
    "id": 2745217,
    "addon": {
      "id": 607454,
      "slug": "ublock-origin"
    },
    "reviewer": {
      "displayName": "Arthur Prazeres"
    },
    "version": {
      "id": 6437252,
      "name": "1.74.0"
    },
    "review": {
      "score": 5,
      "body": null,
      "created": "2026-09-10T12:21:46Z",
      "isDeleted": false,
      "isDeveloperReply": false,
      "isLatest": true,
      "previousCount": 0
    },
    "developerReply": null
  }
]
```

### Run summary

Every completed Apify run exposes its run status and default storage identifiers in the Console and API response. Use `defaultDatasetId` to retrieve the Dataset shown above.

The Actor also declares these run-level output fields:

| Field | Type | Description |
| :--- | :--- | :--- |
| `results` | `string` | Normalized reviews |
| `summary` | `string` | Run summary |

### API Integration

Set `APIFY_TOKEN` in your environment. All examples use the same verified sample input shown above.

#### Node.js (JavaScript)

```javascript
import { ApifyClient } from "apify-client";

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const input = {
  "addons": ["ublock-origin"],
  "maxItems": 1,
  "onlyWithText": false
};
const run = await client.actor("hrMdofCPiW9GMaCsb").call(input);
const { items } = await client.dataset(run.defaultDatasetId).listItems();

console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run_input = {
    "addons": ["ublock-origin"],
    "maxItems": 1,
    "onlyWithText": False
}
run = client.actor("hrMdofCPiW9GMaCsb").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### cURL

```bash
curl --request POST \
  --url "https://api.apify.com/v2/acts/hrMdofCPiW9GMaCsb/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "addons": ["ublock-origin"],
  "maxItems": 1,
  "onlyWithText": false
}
JSON
```

### Pricing & Monetization

This Actor uses Apify's **Pay-Per-Event (PPE)** model.

- Paid action: **Review delivered**
- Event price: **$0.000500**
- Equivalent entity price: **$0.50 per 1,000 events**

The event is intended to represent a unique entity successfully delivered to the Dataset. Platform-level charges, free-tier allowances, or future pricing changes are shown on the Actor's live **Pricing** tab, which is authoritative.

### Limitations & Source Constraints

- The source is Mozilla’s public v5 ratings collection. Other browser stores, private data, authentication-protected content, aggregate add-on statistics, and fields outside the normalized contract are not covered.
- Mozilla’s review collection can change while pages are being retrieved. Deduplication can prevent repeated IDs in the output, but a run is not a point-in-time snapshot and may omit records when the source changes during pagination.
- Review bodies, reviewer display names, and developer replies may be null. A developer reply is included only when the source provides a valid reply object.
- Input URLs are limited to canonical public AMO Firefox add-on or reviews URLs; direct API URLs and URLs containing query parameters are not supported.
- Results contain public user-written text and display names. Users remain responsible for lawful use, privacy, retention, moderation, and appropriate handling of offensive or sensitive material.

### FAQ

#### What can I use as an add-on target?

Use an add-on slug such as ublock-origin or a canonical public addons.mozilla.org Firefox add-on URL, including its reviews form. Supply one or more values in `addons`.

#### Can I collect reviews from several add-ons in one run?

Yes. The `addons` input accepts multiple add-on slugs or canonical AMO URLs, and `maxItems` applies separately to each normalized add-on.

#### Can I retrieve only low-rated or written reviews?

Yes. Select one or more star values from 1 through 5, and enable written reviews only to exclude null, empty, or whitespace-only bodies. If no ratings are selected, all star levels are eligible.

#### How are duplicate reviews identified?

Each review uses Mozilla’s top-level integer rating ID as its primary identity key. The collection process deduplicates records by that ID across the run.

#### Are developer responses included?

When available, a developer response is returned as a structured developerReply object with its ID, add-on, body, creation time, state fields, revision count, and reviewer display name. Otherwise, developerReply is null.

#### Does the output include reviews without comments?

It can. Review body is nullable, as shown by the verified sample. Enable written reviews only when you want records with non-empty text.

#### Where do I find the results after a run?

Normalized review items are stored in the default Dataset. A run summary is stored separately in the default key-value store under OUTPUT.

#### Does this require a browser, proxy, Mozilla login, or API key?

The collection uses ordinary unauthenticated HTTP requests to Mozilla’s public API and does not require browser automation, a proxy, a Mozilla login, a session bootstrap, or private credentials.

### Troubleshooting

- **No Dataset items:** verify the target identifier or URL and check whether active filters exclude all available records.
- **A source request fails:** inspect the run log for the affected input, then retry after a short delay if the public source is temporarily unavailable.
- **A field is missing:** optional source fields can be absent. Compare the item with the verified output reference above before treating it as a schema regression.

### Support & Issue Reporting

When reporting a problem, include the run ID, sanitized input, expected result, and observed result. Never include API tokens or private credentials in an issue.

# Actor input Schema

## `addons` (type: `array`):

Enter add-on slugs or canonical public AMO add-on or reviews URLs. Equivalent targets are normalized and collected once.

## `maxItems` (type: `integer`):

Maximum matching reviews to deliver for each add-on. For example, 3 add-ons × 100 reviews can deliver and bill up to 300 reviews, subject to PPE charge capacity.

## `ratings` (type: `array`):

Choose one or more star ratings, or leave empty to include all ratings.

## `onlyWithText` (type: `boolean`):

When enabled, deliver only reviews with non-empty text.

## Actor input object example

```json
{
  "addons": [
    "ublock-origin"
  ],
  "maxItems": 100,
  "onlyWithText": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addons": [
        "ublock-origin"
    ],
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("genial_candlestand/firefox-addons-reviews-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "addons": ["ublock-origin"],
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("genial_candlestand/firefox-addons-reviews-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addons": [
    "ublock-origin"
  ],
  "maxItems": 100
}' |
apify call genial_candlestand/firefox-addons-reviews-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,genial_candlestand/firefox-addons-reviews-parser"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hrMdofCPiW9GMaCsb/builds/ew64CBfDcjGChRoHr/openapi.json