---
title: "Search"
description: "在 App Store 中搜索应用。"
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/serp/llms.txt)

```http
GET | POST /v1/app-store/search
```

参数可以用 `GET` 的查询字符串发送，也可以用 `POST` 的 JSON 请求体发送，两者等价。

## 请求

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/app-store/search?q=meditation&country=US&limit=10" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ q: "meditation", country: "US", limit: "10" });
const res = await fetch(`https://gateway.apinoa.com/v1/app-store/search?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/app-store/search",
    params={"q": "meditation", "country": "US", "limit": "10"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## 参数

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `country` | enum |  | The market, as an ISO 3166 country code. `US` `GB` `CA` `AU` `NZ` `IE` `DE` `FR` `IT` `ES` `NL` `BE` `AT` `CH` `SE` `NO` `DK` `FI` `PL` `PT` `CZ` `GR` `HU` `RO` `TR` `UA` `IL` `AE` `SA` `EG` `ZA` `NG` `KE` `IN` `PK` `ID` `MY` `SG` `TH` `VN` `PH` `JP` `KR` `CN` `TW` `HK` `MX` `BR` `AR` `CL` `CO` `PE` |
| `cursor` | string |  | The previous page's `cursor`. Pass it alone for the next page. |
| `lang` | string |  | Interface language. |
| `limit` | integer 1–200 |  | Results wanted (default 50, at most 200). More than one page is charged per page. |
| `q` | string |  | The query, search operators included. |

The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json

## 响应

在 `data` 中返回 [`AppsPage`](/docs/api-reference/serp/response-schema#appspage)。 真实响应的节选：数组只保留前几项，长文本已截断。

```json
{
  "success": true,
  "data": {
    "engine": "app-store",
    "query": "meditation",
    "outcome": "results",
    "country": "US",
    "apps": [
      {
        "id": "337472899",
        "name": "Insight Timer: Meditate, Sleep",
        "url": "https://apps.apple.com/us/app/insight-timer-meditate-sleep/id337472899?uo=4",
        "developer": {
          "name": "Insight Network Inc",
          "id": "983080487",
          "url": "https://apps.apple.com/us/developer/insight-network-inc/id983080487?uo=4",
          "website": "http://www.insighttimer.com"
        },
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b7/68/07/b768071e-fb00-0d0f-f9d3-e0e427d85e4b/AppIcon-0-0-1x_U007epad-0-1-85-220.png/512x512bb.jpg",
        "screenshots": [
          "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/9f/89/d3/9f89d364-4d66-e14f-7cff-5be7e3a6445a/0_APP_IPHONE_55_0.png/392x696bb.png",
          "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/79/de/a5/79dea510-d411-3746-a506-82794b4fcd37/1_APP_IPHONE_55_1.png/392x696bb.png"
        ],
        "description": "The world’s most popular wellness app.\n\n* Apps of the Year Winner - TIME magazine and Women's Health *\n* More time is spent on Insight Timer than on all other w…",
        "categories": ["Health & Fitness", "Lifestyle"],
        "rating": {"average": 4.89513, "count": 448546},
        "price": {"currency": "USD", "amount": 0},
        "contentRating": "12+",
        "version": "20.40.0",
        "requires": "Requires iOS 15.0 or later",
        "releasedAt": "2009-11-05T18:55:12Z",
        "updatedAt": "2026-10-25T08:30:36Z",
        "whatsNew": "The world's largest free mental health app just got even bigger! In the last week we've added 925 new free meditations for you to enjoy, plus 500 new free sleep…",
        "ext": {
          "bundleId": "com.spotlightsix.zentimer",
          "languages": ["NL"],
          "sellerName": "Insight Network Inc",
          "sizeBytes": 241229824,
          "formattedPrice": "Free",
          "icons": {
            "60": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b7/68/07/b768071e-fb00-0d0f-f9d3-e0e427d85e4b/AppIcon-0-0-1x_U007epad-0-1-85-220.png/60x60bb.jpg",
            "100": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b7/68/07/b768071e-fb00-0d0f-f9d3-e0e427d85e4b/AppIcon-0-0-1x_U007epad-0-1-85-220.png/100x100bb.jpg",
            "512": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/b7/68/07/b768071e-fb00-0d0f-f9d3-e0e427d85e4b/AppIcon-0-0-1x_U007epad-0-1-85-220.png/512x512bb.jpg"
          },
          "ipadScreenshots": [
            "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/0d/63/ee/0d63eeb3-02e9-d06b-a73b-291a6ae634a3/0_APP_IPAD_PRO_129_0.png/576x768bb.png"
          ],
          "genreIds": ["6013"],
          "primaryGenre": {"id": "6013", "name": "Health & Fitness"},
          "contentAdvisoryRating": "12+",
          "advisories": ["Infrequent/Mild Alcohol, Tobacco, or Drug Use or References"],
          "currentVersionRating": {"average": 4.89513, "count": 448546},
          "minimumOsVersion": "15.0",
          "supportedDevices": ["iPhone5s-iPhone5s"],
          "features": ["iosUniversal"],
          "isGameCenterEnabled": false,
          "isVppDeviceBasedLicensingEnabled": true,
          "kind": "software"
        },
        "rank": 1,
        "country": "US"
      },
      {
        "id": "493145008",
        "name": "Headspace: Sleep & Meditation",
        "url": "https://apps.apple.com/us/app/headspace-sleep-meditation/id493145008?uo=4",
        "developer": {
          "name": "Headspace Inc.",
          "id": "384434796",
          "url": "https://apps.apple.com/us/developer/headspace-inc/id384434796?uo=4",
          "website": "https://www.headspace.com/"
        },
        "icon": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/ec/20/88/ec208862-22e5-ef28-fd52-eff6151054fe/AppIcon-0-0-1x_U007epad-0-1-85-220.png/512x512bb.jpg",
        "screenshots": [
          "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource221/v4/72/5a/ec/725aec3b-ce7e-04e5-3fb2-c3eddd568959/6edb2838-55b4-46d0-b166-358beae09bf2_1242x2208bb__U002…",
          "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/17/aa/29/17aa2961-e804-11d8-d196-58c486554ffe/7cfe3748-bd48-4629-8716-8735363c19b2_1242x2208bb__U002…"
        ],
        "description": "Welcome to Headspace, your expert-led guide to mental health, mindfulness, and meditation. Whether you're navigating stress, anxiety, sleep trouble, or life’s u…",
        "categories": ["Health & Fitness", "Productivity"],
        "rating": {"average": 4.84216, "count": 973755},
        "price": {"currency": "USD", "amount": 0},
        "contentRating": "12+",
        "version": "8.38.1",
        "requires": "Requires iOS 15.6 or later",
        "releasedAt": "2012-02-02T18:57:49Z",
        "updatedAt": "2026-10-28T15:55:23Z",
        "whatsNew": "Thanks for using Headspace! This update includes bug fixes and performance improvements.\n\nAs always, if you run into any troubles, let us know at help@headspace…",
        "ext": {
          "bundleId": "com.getsomeheadspace.headspace",
          "languages": ["EN"],
          "sellerName": "Headspace Inc.",
          "sizeBytes": 451194880,
          "formattedPrice": "Free",
          "icons": {
            "60": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/ec/20/88/ec208862-22e5-ef28-fd52-eff6151054fe/AppIcon-0-0-1x_U007epad-0-1-85-220.png/60x60bb.jpg",
            "100": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/ec/20/88/ec208862-22e5-ef28-fd52-eff6151054fe/AppIcon-0-0-1x_U007epad-0-1-85-220.png/100x100bb.jpg",
            "512": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/ec/20/88/ec208862-22e5-ef28-fd52-eff6151054fe/AppIcon-0-0-1x_U007epad-0-1-85-220.png/512x512bb.jpg"
          },
          "ipadScreenshots": [
            "https://is1-ssl.mzstatic.com/image/thumb/PurpleSource211/v4/33/c1/e8/33c1e8bd-22f2-501b-3d45-b529bb7159f5/1.png/576x768bb.png"
          ],
          "genreIds": ["6013"],
          "primaryGenre": {"id": "6013", "name": "Health & Fitness"},
          "contentAdvisoryRating": "12+",
          "currentVersionRating": {"average": 4.84216, "count": 973755},
          "minimumOsVersion": "15.6",
          "supportedDevices": ["iPhone5s-iPhone5s"],
          "features": ["iosUniversal"],
          "isGameCenterEnabled": false,
          "isVppDeviceBasedLicensingEnabled": true,
          "kind": "software"
        },
        "rank": 2,
        "country": "US"
      }
    ],
    "page": {"index": 1, "size": 9},
    "cursor": "Rl3-aEioiw8jPXTAto6_y35Jx3GMcueBNp5H67_hEE-LLcoHOLkRJZHNmJ8MHqWIVY8iJEvRARMIDnhl2g-NjcqTABxE60OMknPnEWoXagyBpGU6jdqpmklxtd7LcrZEiSFW17vPwmVY1LvT1HqPuHqw_2M2Zfw_…",
    "fetchedAt": "2026-10-30T00:57:25.431Z"
  }
}
```

## 错误

| 状态 | 代码 | 含义 |
|---|---|---|
| 400 | `INVALID_CURSOR` | 该 `cursor` 不是本操作返回的。请不带它重新开始。 |
| 400 | `INVALID_PARAMS` | 参数缺失、未知、超出范围，或该引擎不接受。消息中会指出是哪一个。 |
| 401 | `UNAUTHORIZED` | 缺少 `x-api-key` 请求头，或密钥已吊销或未知。 |
| 402 | `INSUFFICIENT_BALANCE` | 余额不足以支付本次调用。请在控制台充值。 |
| 429 | `MARKETPLACE_SATURATED` | 并发调用过多。请等待 `Retry-After` 秒后重试。 |
| 502 | `UPSTREAM_ERROR` | 引擎返回了无法使用的内容。请退避后重试。 |
| 503 | `SERVICE_UNAVAILABLE` | 临时故障。请退避后重试。 |

全部错误代码见 [Errors](/docs/errors)。失败的调用不计费。

## 价格

**Price** $0.0012 per call. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.