mercapi-node

Live API status: zhu-kai.github.io/mercapi-node — a scheduled check runs every 6 hours against the real Mercari API and fails loudly if the API changes.

Node.js client for Mercari Japan API. TypeScript-first, serverless-friendly.

This project is derived from mercapi by Take-kun.

Disclaimer: This is an unofficial library. Use at your own risk.

Features

Full TypeScript support with type definitions
Covers search, item details, sellers, reviews, similar items, Mercari Shops products, search autocomplete, seller badges, and master data
Serverless-optimized (fresh keys per request by default)
No heavy dependencies (only jose for JWT signing)
ESM and CommonJS support
Node.js 18+ (uses native fetch)

Installation

npm install mercapi

Quick Start

import { Mercapi } from 'mercapi';

const results = await Mercapi.search('iPhone 15');
console.log(`Found ${results.meta.numFound} items`);

for (const item of results.items) {
  console.log(`${item.name}: ¥${item.price}`);
}

Usage Patterns

Pattern 1: Static Methods (Simplest)

Best for serverless. Each call uses fresh keys automatically.

import { Mercapi } from 'mercapi';

const results = await Mercapi.search('Nintendo Switch');
const item = await Mercapi.getItem('m12345678901');
const profile = await Mercapi.getProfile('123456789');
const sellerItems = await Mercapi.getSellerItems('123456789');

Pattern 2: Instance with Fresh Keys (Default)

import { Mercapi } from 'mercapi';

const mercapi = new Mercapi();
const results = await mercapi.search('AirPods'); // Fresh keys
const results2 = await mercapi.search('iPad'); // Fresh keys again

Pattern 3: Instance with Key Reuse

For batched requests where you want to reuse keys:

import { Mercapi } from 'mercapi';

const mercapi = new Mercapi({ reuseKeys: true });
const results1 = await mercapi.search('camera');
const results2 = await mercapi.search('lens');

// Manually rotate keys if needed
await mercapi.rotateKeys();

API Reference

search(query, options?)

Search for items on Mercari.

const results = await Mercapi.search('iPhone', options);

Options

Option	Type	Default	Description
`categories`	`number[]`		Category IDs
`brands`	`number[]`		Brand IDs
`sizes`	`number[]`		Size IDs
`priceMin`	`number`		Minimum price (JPY)
`priceMax`	`number`		Maximum price (JPY)
`itemConditions`	`number[]`		Condition IDs (1-6)
`shippingPayer`	`number[]`		1=buyer, 2=seller
`colors`	`number[]`		Color IDs (1-12)
`status`	`ItemStatus[]`	`[OnSale]`	`OnSale`, `SoldOut`
`sortBy`	`SortBy`	`Score`	Sort field
`sortOrder`	`SortOrder`	`Desc`	Sort direction
`excludeKeyword`	`string`		Keywords to exclude
`pageToken`	`string`		Pagination token
`withAuction`	`boolean`	`true`	Include auction data
`excludeShopItems`	`boolean`	`false`	Exclude Mercari Shops items
`itemTypes`	`ItemType[]`		Restrict to listing types (e.g. Shops only)
`sellerIds`	`string[]`		Restrict to specific sellers

ID-based filters (categories, brands, sizes, etc.) reference Mercari master data. The full lists are in docs/facets/; refresh them anytime with npm run fetch-facets.

Response: `SearchResult`

interface SearchResult {
  items: SearchResultItem[];
  meta: {
    numFound: number; // Total matching items
    nextPageToken: string; // Token for next page
  };
}

interface SearchResultItem {
  id: string; // Item ID (e.g., "m12345678901")
  sellerId: string; // Seller ID
  name: string; // Item title
  price: number; // Price in JPY
  status: string; // Item status
  categoryId: number; // Category ID
  itemConditionId: number; // Condition ID (1-6)
  shippingPayerId: number; // Shipping payer ID
  thumbnails: string[]; // Thumbnail URLs
  created: number; // Creation timestamp
  updated: number; // Last update timestamp
  isShopItem: boolean; // true if Mercari Shops item
  auction?: {
    // Only present for auction items
    id: string;
    endTime: number; // Bid deadline (Unix timestamp, seconds)
    totalBids: number;
    highestBid: number; // Current highest bid in JPY
    initialPrice: number; // Starting price in JPY
  };
  itemBrand?: { id: number; name: string; subName: string };
  shopName?: string; // Only present for Mercari Shops items
}

Example

import { Mercapi, SortBy, SortOrder, ItemCondition, ShippingPayer } from 'mercapi';

const results = await Mercapi.search('AirPods', {
  categories: [8],
  itemConditions: [ItemCondition.BrandNew, ItemCondition.LikeNew],
  shippingPayer: [ShippingPayer.Seller],
  priceMin: 5000,
  priceMax: 20000,
  sortBy: SortBy.Price,
  sortOrder: SortOrder.Asc,
  excludeShopItems: true,
});

// Auction items are flagged via the `auction` field
for (const item of results.items) {
  if (item.auction) {
    console.log(`[Auction] ${item.name}: ¥${item.auction.highestBid} (${item.auction.totalBids} bids)`);
  }
}

getItem(id, options?)

Get detailed item information.

const item = await Mercapi.getItem('m12345678901');

Options

Option	Type	Default	Description
`includeAuction`	`boolean`	`true`	Include auction info

Response: `Item | null`

interface Item {
  id: string;
  name: string;
  price: number;
  description: string;
  status: string;
  photos: string[]; // Full-size image URLs
  thumbnails: string[];
  seller: {
    id: string;
    name: string;
    photoUrl: string;
    numSellItems: number;
    ratings: { good: number; normal: number; bad: number };
    numRatings: number;
    starRatingScore: number; // 1-5
    isFollowable: boolean;
    isBlocked: boolean;
  };
  itemCategory: {
    id: number;
    name: string;
    parentCategoryId: number;
    parentCategoryName: string;
    rootCategoryId: number;
    rootCategoryName: string;
  };
  itemCondition: { id: number; name: string };
  itemBrand?: { id: number; name: string; subName: string };
  shippingPayer: { id: number; name: string; code: string };
  shippingMethod: { id: number; name: string };
  shippingFromArea: { id: number; name: string };
  shippingDuration?: { id: number; name: string; minDays: number; maxDays: number };
  numLikes: number;
  numComments: number;
  comments: Array<{
    id: string;
    message: string;
    user: { id: string; name: string; photoUrl: string };
    created: number;
  }>;
  created: number;
  updated: number;
  isShopItem: boolean;
  isAnonymousShipping: boolean;
  isOfferable: boolean;
  auctionInfo?: {
    // Only present for auction items
    id: string;
    startTime: number;
    endTime: number;
    totalBids: number;
    initialPrice: number;
    highestBid: number;
    state: string; // e.g., "STATE_ONGOING", "STATE_NO_BID"
    auctionType: string;
  };
  itemAttributes?: Record<string, unknown>[]; // Raw dynamic attributes; schema varies by category
}

Example

const item = await Mercapi.getItem('m12345678901');
if (item) {
  console.log(`${item.name}: ¥${item.price}`);
  console.log(`Seller: ${item.seller.name} (★${item.seller.starRatingScore})`);
  console.log(`Category: ${item.itemCategory.name}`);
  console.log(`Condition: ${item.itemCondition.name}`);
  if (item.itemBrand) {
    console.log(`Brand: ${item.itemBrand.name}`);
  }
  if (item.shippingDuration) {
    console.log(`Ships in: ${item.shippingDuration.minDays}-${item.shippingDuration.maxDays} days`);
  }
}

getProfile(userId)

Get seller profile information.

const profile = await Mercapi.getProfile('123456789');

Response: `Profile | null`

interface Profile {
  id: string;
  name: string;
  photoUrl: string;
  introduction: string;
  numSellItems: number;
  ratings: { good: number; normal: number; bad: number };
  numRatings: number;
  starRatingScore: number; // 1-5
  followerCount: number;
  followingCount: number;
  isOrganizationalUser: boolean; // true if business account
  created: number;
}

Example

const profile = await Mercapi.getProfile('123456789');
if (profile) {
  console.log(`${profile.name} (★${profile.starRatingScore})`);
  console.log(`Ratings: ${profile.ratings.good} good, ${profile.ratings.bad} bad`);
  console.log(`Followers: ${profile.followerCount}`);
}

getSellerItems(sellerId, pageToken?, options?)

Get items listed by a seller.

const sellerItems = await Mercapi.getSellerItems('123456789');
const onSaleOnly = await Mercapi.getSellerItems('123456789', undefined, {
  limit: 10,
  status: ['on_sale'],
  excludeArchivedItem: true,
});

Options

Option	Type	Default	Description
`limit`	`number`	`30`	Maximum items to return
`status`	`string[]`	`['on_sale','trading','sold_out']`	Statuses to include
`excludeArchivedItem`	`boolean`	`false`	Skip listings archived by seller

Response: `SellerItems`

interface SellerItems {
  items: Array<{
    id: string;
    name: string;
    price: number;
    status: string;
    thumbnails: string[];
    created: number;
    updated: number;
    isNoPrice: boolean;
    itemBrand?: { id: number; name: string; subName: string };
    auctionInfo?: AuctionInfo; // Only present for auction items
  }>;
  nextPageToken: string;
}

Example

const sellerItems = await Mercapi.getSellerItems('123456789');
for (const item of sellerItems.items) {
  console.log(`${item.name}: ¥${item.price} (${item.status})`);
}

// Pagination
if (sellerItems.nextPageToken) {
  const nextPage = await Mercapi.getSellerItems('123456789', sellerItems.nextPageToken);
}

getReviews(userId, options?)

Get reviews written about a user, newest first.

const reviews = await Mercapi.getReviews('123456789', { limit: 10 });
for (const r of reviews) {
  console.log(`[${r.fame}] ${r.user.name}: ${r.message}`);
}

// Older reviews: pass the last review's pagerId - 1
const older = await Mercapi.getReviews('123456789', {
  limit: 10,
  maxPagerId: reviews[reviews.length - 1].pagerId - 1,
});

interface Review {
  subject: string; // Role of the reviewed user: 'seller' | 'buyer'
  fame: string; // 'good' | 'normal' | 'bad'
  message: string;
  user: { id: string; name: string; photoUrl: string };
  created: number;
  pagerId: number; // Pagination cursor
}

getSimilarItems(itemId, options?)

Get items similar to a listing, as shown on the item page. Accepts { limit?: number } (default 15).

const similar = await Mercapi.getSimilarItems('m12345678901', { limit: 10 });

interface SimilarItem {
  id: string; // Item ID or Shops product ID
  name: string;
  price: number;
  status: string;
  thumbnail: string;
  itemType: string; // 'ITEM_TYPE_MERCARI' | 'ITEM_TYPE_BEYOND'
  auctionHighestBid?: number; // Only present for auction items
}

getSearchSuggestions(query)

Search bar autocomplete: suggested keywords with category context for a partial query.

const suggestions = await Mercapi.getSearchSuggestions('ニンテンド');
// [{ keyword: 'ニンテンドースイッチ', title: ..., subtitle: 'テレビゲーム', categories: [{ id: 76, name: 'テレビゲーム' }] }, ...]

getShopsProduct(productId)

Get Mercari Shops product details. Search results with itemType of ITEM_TYPE_BEYOND (i.e. isShopItem: true) are Shops products; getItem() does not work for them.

const results = await Mercapi.search('switch', { itemTypes: [ItemType.Beyond] });
const product = await Mercapi.getShopsProduct(results.items[0].id);

interface ShopsProduct {
  id: string;
  displayName: string;
  price: number;
  productTags: string[]; // e.g. ['sold_out']
  thumbnail: string;
  created: number;
  updated: number;
  photos: string[];
  description: string;
  shop?: {
    id: string;
    displayName: string;
    thumbnail: string;
    score: number;
    reviewCount: number;
  };
  productDetail?: Record<string, unknown>; // Raw remaining data (categories, condition, shipping, variants, ...)
}

Returns null if the product does not exist.

getSellerBadges(userId) / hasIdentityVerifiedBadge(userId)

Seller achievement badges and identity verification (本人確認) status.

const badges = await Mercapi.getSellerBadges('123456789');
// [{ id: 10004, name: '高評価', description: ..., iconUrl: ... }, ...]

const verified = await Mercapi.hasIdentityVerifiedBadge('123456789'); // boolean

getDesiredPriceInfo(itemId)

Aggregated "desired price" (希望価格) registrations for a listing.

const info = await Mercapi.getDesiredPriceInfo('m12345678901');
// { itemId, registeredCount, highestDesiredPrice, lowestDesiredPrice, highestDesiredPriceCount }

getMasterData(dataset)

Reference (master) data enumerating IDs usable in search filters. Returns raw JSON since the schema differs per dataset.

const conditions = await Mercapi.getMasterData('itemConditions');

Available datasets: itemCategories, itemCategoryGroups, itemBrands, shippingMethods, itemSizes, itemColors, itemConditions, shippingPayers.

Pagination

let pageToken: string | undefined;

do {
  const results = await Mercapi.search('manga', {
    pageToken,
    sortBy: SortBy.CreatedTime,
    sortOrder: SortOrder.Desc,
  });

  for (const item of results.items) {
    console.log(item.name);
  }

  pageToken = results.meta.nextPageToken || undefined;
} while (pageToken);

Enums

SortBy

Value	Description
`SortBy.Score`	Relevance (default)
`SortBy.CreatedTime`	Newest first
`SortBy.Price`	Price
`SortBy.NumLikes`	Number of likes

SortOrder

Value	Description
`SortOrder.Desc`	Descending (default)
`SortOrder.Asc`	Ascending

ItemStatus

Value	Description
`ItemStatus.OnSale`	Currently on sale
`ItemStatus.SoldOut`	Sold out

ItemType

Value	Description
`ItemType.Mercari`	Regular listing (individual seller)
`ItemType.Beyond`	Mercari Shops listing

ItemCondition

Value	ID	Japanese	English
`ItemCondition.BrandNew`	1	新品、未使用	Brand new
`ItemCondition.LikeNew`	2	未使用に近い	Like new
`ItemCondition.Good`	3	目立った傷や汚れなし	Good
`ItemCondition.Fair`	4	やや傷や汚れあり	Fair
`ItemCondition.Poor`	5	傷や汚れあり	Poor
`ItemCondition.Bad`	6	全体的に状態が悪い	Bad

ShippingPayer

Value	ID	Japanese	English
`ShippingPayer.Buyer`	1	着払い	Buyer pays
`ShippingPayer.Seller`	2	送料込み	Seller pays (free shipping)

Color

Value	ID
`Color.Black`	1
`Color.White`	2
`Color.Gray`	3
`Color.Brown`	4
`Color.Red`	5
`Color.Pink`	6
`Color.Purple`	7
`Color.Blue`	8
`Color.Beige`	9
`Color.Green`	10
`Color.Yellow`	11
`Color.Orange`	12

Reference Data

For facet IDs (categories, brands, sizes, etc.), see: https://github.com/take-kun/mercapi/tree/main/docs/facets

Top-Level Categories

ID	Japanese	English
1	レディース	Women's
2	メンズ	Men's
3	ベビー・キッズ	Baby & Kids
4	インテリア・住まい・小物	Interior
5	本・音楽・ゲーム	Books/Music/Games
6	おもちゃ・ホビー・グッズ	Toys/Hobbies
7	コスメ・香水・美容	Cosmetics
8	家電・スマホ・カメラ	Electronics
9	スポーツ・レジャー	Sports
10	ハンドメイド	Handmade
11	チケット	Tickets
12	自動車・オートバイ	Vehicles
13	その他	Other

Error Handling

All methods throw errors on API failures. Use try-catch for error handling:

import { Mercapi } from 'mercapi';

try {
  const results = await Mercapi.search('iPhone');
} catch (error) {
  // Error message format: "{Method} failed: {status} {statusText}"
  // e.g., "Search failed: 500 Internal Server Error"
  console.error(error.message);
}

Return Values

Method	Not Found	Error
`search()`	Returns `{ items: [], meta: { numFound: 0 } }`	Throws Error
`getItem()`	Returns `null`	Throws Error
`getProfile()`	Returns `null`	Throws Error
`getSellerItems()`	Returns `{ items: [], nextPageToken: '' }`	Throws Error

TypeScript

All types are exported for full TypeScript support:

import {
  // Main class
  Mercapi,
  createMercapi,

  // Options type
  type MercapiOptions,

  // Enums
  SortBy,
  SortOrder,
  ItemStatus,
  ItemCondition,
  ShippingPayer,
  Color,

  // Search types
  type SearchOptions,
  type SearchResult,
  type SearchResultItem,
  type SearchMeta,
  type SearchAuction,

  // Item types
  type Item,
  type Seller,
  type ItemCategory,
  type ItemConditionInfo,
  type ItemBrand,
  type ShippingPayerInfo,
  type ShippingMethodInfo,
  type ShippingFromArea,
  type ShippingDuration,
  type Comment,
  type AuctionInfo,

  // Profile types
  type Profile,
  type SellerItem,
  type SellerItems,
} from 'mercapi';

Type Examples

import { Mercapi, SearchResult, Item, Profile } from 'mercapi';

// Function with typed return
async function searchItems(keyword: string): Promise<SearchResult> {
  return Mercapi.search(keyword);
}

// Nullable item
async function getItemSafe(id: string): Promise<Item | null> {
  return Mercapi.getItem(id);
}

// Type guard for auction items
function isAuctionItem(item: Item): boolean {
  return item.auctionInfo !== undefined;
}

Integration Examples

Express.js API

import express from 'express';
import { Mercapi, SortBy, SortOrder } from 'mercapi';

const app = express();

app.get('/api/search', async (req, res) => {
  try {
    const { q, minPrice, maxPrice, page } = req.query;

    const results = await Mercapi.search(q as string, {
      priceMin: minPrice ? Number(minPrice) : undefined,
      priceMax: maxPrice ? Number(maxPrice) : undefined,
      pageToken: page as string,
      sortBy: SortBy.CreatedTime,
      sortOrder: SortOrder.Desc,
    });

    res.json(results);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.get('/api/items/:id', async (req, res) => {
  try {
    const item = await Mercapi.getItem(req.params.id);
    if (!item) {
      return res.status(404).json({ error: 'Item not found' });
    }
    res.json(item);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

AWS Lambda

import { Mercapi } from 'mercapi';

export const handler = async (event: any) => {
  const keyword = event.queryStringParameters?.q || '';

  try {
    // Static methods are ideal for Lambda - fresh keys each invocation
    const results = await Mercapi.search(keyword);

    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(results),
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message }),
    };
  }
};

Batch Processing

import { Mercapi } from 'mercapi';

async function batchFetchItems(itemIds: string[]) {
  // Use instance with key reuse for batch operations
  const client = new Mercapi({ reuseKeys: true });

  const results = await Promise.all(itemIds.map((id) => client.getItem(id)));

  return results.filter((item): item is NonNullable<typeof item> => item !== null);
}

Monitoring New Listings

import { Mercapi, SortBy, SortOrder } from 'mercapi';

async function monitorNewListings(keyword: string, callback: (items: any[]) => void) {
  let lastSeenId: string | undefined;

  setInterval(async () => {
    try {
      const results = await Mercapi.search(keyword, {
        sortBy: SortBy.CreatedTime,
        sortOrder: SortOrder.Desc,
      });

      const newItems = lastSeenId
        ? results.items
            .filter((item) => item.id !== lastSeenId)
            .slice(
              0,
              results.items.findIndex((i) => i.id === lastSeenId)
            )
        : results.items;

      if (newItems.length > 0) {
        lastSeenId = results.items[0].id;
        callback(newItems);
      }
    } catch (error) {
      console.error('Monitor error:', error);
    }
  }, 60000); // Check every minute
}

Known Issues

Key Rotation

The original Python mercapi has a known issue where search results may differ from browser results after extended use. This is likely due to stale ECDSA keys.

Our solution: By default, this library generates fresh keys for each request, avoiding this issue entirely. This is ideal for serverless environments where each invocation is independent.

If you need to reuse keys (e.g., for performance in batch operations), use reuseKeys: true and call rotateKeys() periodically.

Credits

This project is a TypeScript/Node.js port of mercapi by take-kun, which pioneered the reverse-engineering of the Mercari Japan API, including the DPoP request signing scheme and the auction/shop item response formats. All API insights originate from that project — please consider starring it if you find this library useful.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs/facets		docs/facets
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
example.ts		example.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

mercapi-node

Features

Installation

Quick Start

Usage Patterns

Pattern 1: Static Methods (Simplest)

Pattern 2: Instance with Fresh Keys (Default)

Pattern 3: Instance with Key Reuse

API Reference

search(query, options?)

Options

Response: SearchResult

Example

getItem(id, options?)

Options

Response: Item | null

Example

getProfile(userId)

Response: Profile | null

Example

getSellerItems(sellerId, pageToken?, options?)

Options

Response: SellerItems

Example

getReviews(userId, options?)

getSimilarItems(itemId, options?)

getSearchSuggestions(query)

getShopsProduct(productId)

getSellerBadges(userId) / hasIdentityVerifiedBadge(userId)

getDesiredPriceInfo(itemId)

getMasterData(dataset)

Pagination

Enums

SortBy

SortOrder

ItemStatus

ItemType

ItemCondition

ShippingPayer

Color

Reference Data

Top-Level Categories

Error Handling

Return Values

TypeScript

Type Examples

Integration Examples

Express.js API

AWS Lambda

Batch Processing

Monitoring New Listings

Known Issues

Key Rotation

Credits

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Response: `SearchResult`

Response: `Item | null`

Response: `Profile | null`

Response: `SellerItems`