# Japan Anime Figure Demand Features (`fruitful_quintessence/japan-anime-figure-demand-features`) Actor

- **URL**: https://apify.com/fruitful\_quintessence/japan-anime-figure-demand-features.md
- **Developed by:** [atushi ino](https://apify.com/fruitful_quintessence) (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

from $2.00 / 1,000 results

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

## Japan Anime Figure Demand Feature Vectors

**Fixed-dimension (48), normalized feature vectors for 650+ Japan anime/figure SKUs** — purpose-built for AI agents, ML training pipelines and quant research.

Derived from the multi-shop price snapshot published by
[`japan-anime-figure-price-data`](https://apify.com/atushi/japan-anime-figure-price-data).
No scraping happens at run time: this Actor re-projects an already-collected
dataset into a machine-consumable feature matrix.

> **What this is not:** it is not a back-tested price forecast. See
> [Limitations](#limitations) before you build on it.

***

### Quick start

```bash
npx @apify/apify-cli run atushi/japan-anime-figure-demand-features --input '{
  "hasPriceOnly": true,
  "minDemandScore": 0.35,
  "limit": 50
}'
```

### Call it from Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("japan-anime-figure-demand-features").call(
    run_input={"hasPriceOnly": True, "minDemandScore": 0.35, "limit": 50}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["figureId"], item["demandScore"], item["vector"][:5])
```

### Call it over HTTP

```bash
curl -s "https://api.apify.com/v2/acts/atushi~japan-anime-figure-demand-features/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"hasPriceOnly": true, "limit": 10}' | jq '.[0] | {figureId, demandScore, featureDim}'
```

***

### Output shape

Every dataset item:

| Field | Type | Meaning |
|---|---|---|
| `schemaVersion` | string | Feature-vector schema version (semver) |
| `featureDim` | int | Length of `vector`; always 48 today |
| `figureId` | string | Stable upstream SKU id |
| `name`, `series`, `manufacturer`, `category`, `janCode` | string | Identity |
| `demandScore` | number | Composite demand proxy in `[0,1]` |
| `history` | object | `points`, `firstSeen`, `lastSeen`, `velocityAvailable` |
| `coverage` | object | `hasOfferDetail`, `offerDetailRows`, `hasAggregatePrice`, `hasMsrp`, `hasJan` |
| `features` | object | 48 named features (canonical order) |
| `featureNames` | array | Ordered names; `featureNames[i]` ↔ `vector[i]` |
| `vector` | array | 48 floats in `featureNames` order |

The full schema manifest ships in the run's key-value store as
`FEATURE_MANIFEST` (dimension, ordered names, per-dimension documentation and
normalization constants). Fetch it once and build your column mapping from it
instead of hard-coding indices.

### Feature groups

| Group | Count | Examples |
|---|---|---|
| Price | 8 | `price_min_norm`, `msrp_norm`, `discount_depth`, `premium_ratio` |
| Supply | 8 | `stock_ratio`, `offer_count_norm`, `shop_diversity_ratio` |
| Cross-shop dispersion | 4 | `shop_price_cv`, `cheapest_shop_advantage`, `instock_price_premium` |
| Temporal | 8 | `age_days_norm`, `release_year_norm`, `velocity_7d`, `history_available` |
| Metadata completeness | 8 | `has_msrp`, `has_jan`, `confidence` |
| Categorical / identity | 8 | `is_scale_figure`, `manufacturer_pop_norm`, hash-bucket embeddings |
| Relative price rank | 3 | `price_rank_in_series`, `price_rank_in_category`, `price_rank_in_manufacturer` |
| Composite | 1 | `demand_score` |

Normalization: every component lies in `[0,1]`, except `instock_price_premium`
and `velocity_*` which are clipped to `[-1,1]`. Absolute prices are divided by
50,000 JPY and offer counts by 30 — both constants are exposed in the manifest.

#### `demand_score`

```
demand_score = 0.35 * stock_ratio
             + 0.25 * log_offer_count_norm
             + 0.20 * discount_depth
             + 0.10 * (1 - age_days_norm)
             + 0.10 * (1 - price_spread_ratio)
```

A supply-side demand-pressure proxy. It is **not** a forecast and has **not**
been back-tested against realised sales.

***

### Limitations

- **Single collection point.** The shipped upstream snapshot was captured on
  one date, so `history.points` is `1` for the 132 rows that carry offer
  detail and `0` for the rest. `velocity_7d` / `velocity_30d` are therefore
  emitted as `0.0`. Gate on `history_available == 1.0` before using velocity
  features; where it is `0.0` the values carry no information.
- **Aggregate-only rows.** 181 upstream rows advertise a non-zero offer count
  (and often a price) while shipping an empty `offers[]` array. Price features
  still resolve from the aggregate figures, but every per-shop feature
  (`shop_price_cv`, `shop_price_range_ratio`, `cheapest_shop_advantage`,
  `distinct_shop_norm`, `shop_diversity_ratio`, `instock_price_premium`) is
  `0.0` for them — read `coverage.hasOfferDetail` first, or pass
  `requireOfferDetail: true`.
- **Sparse price coverage.** 292 of 654 upstream rows carry a price; the rest
  have metadata only. Use `hasPriceOnly: true` to exclude them.
- **Hash-bucket embeddings.** `manufacturer_bucket_norm` and friends are
  deterministic SHA-256 buckets, not trained embeddings. They give models a
  stable categorical signal, not semantics.
- **Japan-market scope.** Figures, hobby goods and their secondary market only.

### Pricing

Pay-Per-Event, **$0.002 per dataset item returned** — the account-standard
price point shared by 46 of 73 portfolio Actors. A one-time Actor-start event
applies per run (`$0.00005` per GB of memory). No subscription, no minimum.

### Input reference

| Field | Type | Default | Notes |
|---|---|---|---|
| `figureIds` | string\[] | – | Restrict to specific upstream SKUs |
| `series` / `character` / `manufacturer` | string | – | Case-insensitive partial match |
| `categories` | string\[] | – | `Scale Figure`, `Anime Figure` |
| `minDemandScore` / `maxDemandScore` | number | – | Filter on `demandScore` |
| `hasPriceOnly` | bool | `false` | Drop rows with no observed price |
| `requireOfferDetail` | bool | `false` | Drop rows with an empty `offers[]` |
| `includeFeatures` | bool | `true` | Attach named feature dict |
| `includeVector` | bool | `true` | Attach ordered vector |
| `limit` / `offset` | int | `100` / `0` | Ordered by descending `demandScore`, then `figureId` |

### Provenance

Upstream dataset: `japan-anime-figure-price-data` (MyFigureList primary, 23
distinct shops observed, JAN/GTIN keyed where available). Each record carries
`sourcesMerged` and `confidence` from the upstream collector via
`provenance` in the manifest pipeline.

### License

MIT.

# Actor input Schema

## `figureIds` (type: `array`):

Optional list of upstream figure IDs to restrict the result set.

## `series` (type: `string`):

Filter by series name (partial, case-insensitive match).

## `character` (type: `string`):

Filter by character name (partial, case-insensitive match).

## `manufacturer` (type: `string`):

Filter by manufacturer name (partial, case-insensitive match).

## `categories` (type: `array`):

Restrict to specific upstream categories (e.g. Scale Figure, Anime Figure).

## `minDemandScore` (type: `number`):

Only return SKUs whose composite demand score is >= this value (0.0-1.0).

## `maxDemandScore` (type: `number`):

Only return SKUs whose composite demand score is <= this value (0.0-1.0).

## `hasPriceOnly` (type: `boolean`):

Skip SKUs with no observed price data (522 of 654 rows have no live offers).

## `requireOfferDetail` (type: `boolean`):

Only return SKUs whose upstream row carries a populated offers\[] array. Recommended when you rely on per-shop features (shop\_price\_cv, distinct\_shop\_norm, instock\_price\_premium): 181 upstream rows advertise an aggregate offer count but ship no offer detail, so those features are 0 for them.

## `includeFeatures` (type: `boolean`):

Attach the named feature dictionary and feature-name list to each record.

## `includeVector` (type: `boolean`):

Attach the canonical ordered 48-dimensional float vector to each record.

## `limit` (type: `integer`):

Maximum number of records to return.

## `offset` (type: `integer`):

Pagination offset (records are ordered by descending demand score, then figure ID).

## Actor input object example

```json
{
  "hasPriceOnly": false,
  "requireOfferDetail": false,
  "includeFeatures": true,
  "includeVector": true,
  "limit": 100,
  "offset": 0
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset: one record per SKU with a named feature dictionary, canonical ordered vector and demand-score proxy.

## `manifest` (type: `string`):

Key-value store record FEATURE\_MANIFEST: schemaVersion, featureDim, ordered featureNames, per-dimension documentation and normalization constants.

# 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("fruitful_quintessence/japan-anime-figure-demand-features").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("fruitful_quintessence/japan-anime-figure-demand-features").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 fruitful_quintessence/japan-anime-figure-demand-features --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fruitful_quintessence/japan-anime-figure-demand-features"
        }
    }
}
```

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/8cCUNDwmelphhoXFs/builds/vP77I4gbM3MRAe3uX/openapi.json