> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Apps

> Search apps by keyword or look up by App ID

```
GET /v1/search
```

Search apps by keyword. On the Apple App Store, a numeric query performs a **direct App ID lookup** instead of a keyword search. Pass `platform=google` to search Google Play instead.

## Query Parameters

| Name     | Type   | Default | Required | Description                                                                      |
| -------- | ------ | ------- | -------- | -------------------------------------------------------------------------------- |
| q        | string | —       | Yes      | Search query (minimum 2 characters) or numeric App ID (Apple)                    |
| platform | string | `apple` | No       | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | `us`    | No       | ISO country code (e.g. `us`, `gb`, `de`)                                         |
| lang     | string | `en`    | No       | Google Play language code (used when `platform=google`)                          |
| limit    | number | `20`    | No       | Max results to return (1–50, capped at **50**)                                   |

<Note>
  The `limit` parameter is capped at **50**. Any value above 50 will be silently reduced to 50. The minimum query length is 2 characters — shorter queries will return a `400` error.
</Note>

## Code Examples

### Keyword Search

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/search?q=puzzle%20games&country=us&limit=20" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/search?q=puzzle%20games&country=us&limit=20",
    {
      headers: {
        "X-API-Key": "YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.appeeky.com/v1/search",
      params={"q": "puzzle games", "country": "us", "limit": 20},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

### Google Play Search

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X GET "https://api.appeeky.com/v1/search?q=puzzle%20games&platform=google&country=us&lang=en" \
  -H "X-API-Key: YOUR_API_KEY"
```

For Google Play, results use package names (e.g. `com.king.candycrushsaga`) as the app `id`.

### Numeric App ID Lookup

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.appeeky.com/v1/search?q=1617391485" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.appeeky.com/v1/search?q=1617391485",
    {
      headers: {
        "X-API-Key": "YOUR_API_KEY",
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  response = requests.get(
      "https://api.appeeky.com/v1/search",
      params={"q": "1617391485"},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

## Response — Keyword Search

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "apps": [
      {
        "id": "1617391485",
        "title": "Block Blast!",
        "developer": "Hungry Studio",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg"
      },
      {
        "id": "544007664",
        "title": "Candy Crush Saga",
        "developer": "King",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/.../512x512bb.jpg"
      },
      {
        "id": "1040639975",
        "title": "Hexa Sort",
        "developer": "IEC Global Pty Ltd",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg"
      }
    ]
  }
}
```

## Response — Numeric App ID Lookup

When `q` is a numeric string, the API performs a direct iTunes Lookup and returns the single matching app:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "apps": [
      {
        "id": "1617391485",
        "title": "Block Blast!",
        "developer": "Hungry Studio",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/.../512x512bb.jpg"
      }
    ]
  }
}
```

## App Object

| Field     | Type   | Description          |
| --------- | ------ | -------------------- |
| id        | string | Apple App ID         |
| title     | string | App name             |
| developer | string | Developer name       |
| iconUrl   | string | App icon URL (512px) |

<Tip>
  **Numeric queries**: When `q` is a number (e.g. `1617391485`), the API bypasses the iTunes Search API and performs a **direct iTunes Lookup** by App ID. This returns exactly one result and is faster and more reliable than keyword searching when you already know the App ID.
</Tip>

## Errors

| Status | Code              | When                            |
| ------ | ----------------- | ------------------------------- |
| 400    | INVALID\_QUERY    | Query shorter than 2 characters |
| 400    | INVALID\_LIMIT    | Limit is not a valid number     |
| 401    | MISSING\_API\_KEY | No API key in the request       |
| 401    | INVALID\_API\_KEY | Invalid or expired API key      |