# App Store Launch Detector — Country, Date & Category (`agency-shift/app-store-launch-detector`) Actor

Find recently released iOS apps by country, release date and category. Combine Apple feeds, charts and search; check Apple-reported release dates and retain first-seen history. Export deduplicated observations with source links. Bounded coverage.

- **URL**: https://apify.com/agency-shift/app-store-launch-detector.md
- **Developed by:** [Mako](https://apify.com/agency-shift) (community)
- **Categories:** Developer tools, Marketing
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.03 / actor start

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## App Store Launch Detector — country, release date and category

Find recently released iOS apps available in selected Apple App Store countries. Combine Apple's new-app feed, top charts and optional keyword searches, then verify each candidate through country-specific iTunes Lookup. Filter by **Apple-reported original release date** and category, and retain a private history for repeat monitoring.

Useful for app-market research, ASO teams, developer discovery and app-launch research workflows. No Apple credentials, proxy subscription or paid child Actor is required. This Actor reuses the public Apple collection approach in Mako's App Store search and chart Actors.

### First run

```json
{
  "countries": ["us", "gb"],
  "daysBack": 30,
  "categoryIds": [],
  "includeNewReleases": true,
  "includeCharts": true,
  "monitorName": "recent-apps-us-gb",
  "maxResults": 100
}
```

Open the dataset for matches and the **SUMMARY** record for verified candidate counts, exclusions and source limits. A first monitoring run returns `initial_release_match` rows. Repeat the same input and monitor name to receive only additional qualifying observations. An unchanged repeat can correctly return zero rows.

For a fixed date range, use `releaseDateFrom` and optionally `releaseDateTo` as `YYYY-MM-DD`. Both days are inclusive in UTC. Explicit dates override `daysBack`. Choose a new monitor name when changing date rules or discovery filters.

```json
{
  "countries": ["de", "fr"],
  "releaseDateFrom": "2026-09-01",
  "releaseDateTo": "2026-09-30",
  "categoryIds": ["6007"],
  "keywords": ["productivity"],
  "historyMode": "snapshot"
}
```

This searches today's bounded sources for apps with those original release dates. It does **not** recreate September's complete app catalogue, rankings or availability history.

### Filters and collection limits

| Input | Meaning |
|---|---|
| `countries` | Up to 5 Apple storefront codes, such as `us`, `gb`, `ie`, `de`, `fr`, `br`. Country means the storefront queried. |
| `daysBack` | Last 1–365 UTC calendar days, including today; default 30. |
| `releaseDateFrom`, `releaseDateTo` | Optional original-release date range. End defaults to today. Future releases are excluded, including future timestamps today. |
| `categoryIds` | Up to 5 Apple genre IDs. Matches primary or secondary genre. Empty means any category. Examples: `6007` Productivity, `6000` Business, `6017` Education, `6014` Games. |
| `keywords` | Up to 8 optional Apple searches to add candidates. Results are not ordered by release date. |
| `includeNewReleases` | Include Apple's `newapplications` feed; default true. Membership does not prove recency. |
| `includeCharts`, `chartTypes` | Include available free/paid charts; default top-free. Missing charts cause a visible failure, not a silent switch. |
| `appIds` | Up to 100 known app IDs to verify; these are prioritized before discovery sources. |
| `monitorName` | A private reusable history name, default `default`. Keep filters consistent or use another name. |
| `outputMode` | `new` suppresses previously delivered matches; `all` returns qualifying observations again. |
| `historyMode` | `monitor` saves history; `snapshot` performs an independent lookup without accessing history. |
| `perSourceLimit` | 1–200 candidates per feed/search, default 100. Apple may ignore its requested limit; we enforce this locally. |
| `maxCandidates` | Total distinct app-country candidates, default 500, maximum 2,000. |
| `maxResults` | Delivered rows this run, default 100. Undelivered eligible matches remain queued in monitor mode. |
| `maxRequests` | Discovery plus verification requests, default 40, maximum 80. Reduce scope if verification cannot finish. |
| `requestTimeoutSecs` | Per-request timeout, default 25 seconds. Collection is paced and limited to 330 seconds overall. |

An app present in two countries produces two country observations. Apps found through multiple sources in the same country are deduplicated.

### What each result tells you

- App ID, name, developer, category, price, rating, languages and App Store link.
- `releaseDate`: Apple's reported app release timestamp, checked through Lookup. It is not independent proof of the app’s first-ever worldwide launch.
- `currentVersionReleaseDate`: the latest version's date, kept separate and never substituted for launch date.
- `firstSeenAt`: when this monitor first observed that app in this country. This is our own history, starting with your runs.
- `observedAt`: when the delivered observation was collected. Queued observations retain their original timestamp.
- `eventType`: `initial_release_match`, `new_release_match` or one-off `snapshot`.
- `eventId`: a stable identifier for downstream deduplication; source links are included as evidence.

`launchCountryConfirmed` is always false: Apple lookup availability in a storefront does not establish the app's first release date in that specific country. A `new_release_match` means newly qualifying for your monitor and release window, not a claim we observed a launch at that exact moment.

### Monitoring and integrations

Run on demand through the Apify API or create an Apify schedule using the same input and monitor name. Monitoring runs only when you run or schedule it; publishing the Actor does not create a schedule. Use the dataset's JSON, CSV or Excel export with n8n, Make, a spreadsheet or your own application. Scheduling, alert delivery and integrations are configured by you; this Actor does not send messages itself.

History is isolated by the running user, Actor and monitor name. Concurrent runs of the same monitor are prevented by a renewable lock. Changing discovery/date scope requires a new monitor name. No historical entry is silently deleted because an app is absent from a later source sample. History is limited to 50,000 app-country entries; start another monitor if this limit is reached.

Output delivery is at least once: a crash after dataset delivery but before saving its acknowledgement can repeat a row. Deduplicate on `eventId` downstream. A source failure does not accept a partial collection into history. Matches pending because of `maxResults` are rechecked against the date window before later delivery.

### Coverage and limitations

This is **bounded discovery, not every app launched worldwide**. Apple's new-app feed can include old apps or future releases and can ignore category and limit parameters. We verify metadata and apply release/category filters afterward. Country charts and keyword searches are limited samples; absent results do not prove no launches occurred.

No download estimates, revenue estimates, guaranteed contact emails, instant alerts or complete historical backfill are provided. Google Play is not included in this version. Missing original release dates and future releases are excluded and counted in SUMMARY. A changed, unavailable or blocked source produces an error with its request status rather than a false empty success.

### Pricing

Launch price: **$0.03 per Actor-start event**, minimum one event per run; Apify counts startup events per allocated GB, with a minimum of one. This version allows 256–512 MB, so the normal run uses one event. There is **no per-result fee and no paid child scraper**. Startup is charged even when no matching new apps are found or a source fails. Consult the live Pricing tab for the active price and any tier discounts before running. Free-plan credit use is subject to Apify's rules.

### Support

Open an issue with your run URL, country/category filters and the expected behavior. Never post tokens or credentials. This is an independently developed tool, not an Apple product or an exhaustive App Store data service.

# Actor input Schema

## `countries` (type: `array`):

Apple storefront codes, up to 5: us, gb, ie, de, fr, br, jp. A storefront is not proof of the local launch date.

## `daysBack` (type: `integer`):

Last N UTC calendar days including today. Used when no explicit releaseDateFrom is supplied.

## `releaseDateFrom` (type: `string`):

Inclusive YYYY-MM-DD in UTC. Uses Apple original releaseDate, never the last update date. Overrides daysBack.

## `releaseDateTo` (type: `string`):

Inclusive YYYY-MM-DD in UTC. Requires releaseDateFrom. Defaults to today. Future releases are excluded.

## `categoryIds` (type: `array`):

Match any supplied Apple genre ID against primary genre or genreIds. Examples: 6007 Productivity, 6000 Business, 6017 Education, 6014 Games, 6008 Photo & Video. Empty means all categories.

## `keywords` (type: `array`):

Up to 8 Apple search terms. Search results are not chronological; launch-date/category filters are applied afterward.

## `includeNewReleases` (type: `boolean`):

Use newapplications as candidates. Its name does not prove recency; original release dates are verified by Lookup.

## `includeCharts` (type: `boolean`):

Add apps appearing in free/paid country charts. Chart appearance is not itself a launch.

## `chartTypes` (type: `array`):

Supported: topfreeapplications, toppaidapplications. Availability depends on Apple.

## `appIds` (type: `array`):

Also verify supplied numeric Apple app IDs in each selected country. Useful for a watchlist.

## `monitorName` (type: `string`):

Reuse the same name and filters to retain history. Use a different name when changing countries, keywords, date rules or categories.

## `outputMode` (type: `string`):

New returns qualifying apps not previously delivered in this monitor. All returns all qualifying observations again.

## `historyMode` (type: `string`):

Monitor keeps private per-user history. Snapshot performs a one-off search without reading or updating saved history.

## `perSourceLimit` (type: `integer`):

Local cap per feed/search. Apple can ignore its own requested feed limit. Bounded sources can miss matching apps.

## `maxCandidates` (type: `integer`):

Total distinct app-country candidates across sources. Explicit app IDs are prioritized.

## `maxResults` (type: `integer`):

Matching rows delivered this run. In monitor mode eligible pending rows remain available to resume.

## `maxRequests` (type: `integer`):

Includes discovery and metadata verification. If verification cannot complete within this limit, the run fails without accepting a partial source collection.

## `requestTimeoutSecs` (type: `integer`):

Timeout for each Apple request. Requests are paced; the collector has a 330-second total runtime limit.

## Actor input object example

```json
{
  "countries": [
    "us"
  ],
  "daysBack": 30,
  "categoryIds": [],
  "keywords": [],
  "includeNewReleases": true,
  "includeCharts": true,
  "chartTypes": [
    "topfreeapplications"
  ],
  "appIds": [],
  "monitorName": "default",
  "outputMode": "new",
  "historyMode": "monitor",
  "perSourceLimit": 100,
  "maxCandidates": 500,
  "maxResults": 100,
  "maxRequests": 40,
  "requestTimeoutSecs": 25
}
```

# Actor output Schema

## `observations` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("agency-shift/app-store-launch-detector").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("agency-shift/app-store-launch-detector").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 '{}' |
apify call agency-shift/app-store-launch-detector --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,agency-shift/app-store-launch-detector"
        }
    }
}
```

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/6OQOzqAfv05jhfEaW/builds/O5vnlzxIu68Y787yR/openapi.json