Search apps by keyword using the iTunes Search API. If the query is a numeric string, it performs a direct App ID lookup instead of a keyword search.
Query Parameters
| Name | Type | Default | Required | Description |
|---|
| q | string | — | Yes | Search query (minimum 2 characters) or numeric App ID |
| country | string | us | No | ISO country code (e.g. us, gb, de) |
| limit | number | 20 | No | Max results to return (1–50, capped at 50) |
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.
Code Examples
Keyword Search
curl -X GET "https://api.appeeky.com/v1/search?q=puzzle%20games&country=us&limit=20" \
-H "X-API-Key: YOUR_API_KEY"
Numeric App ID Lookup
curl -X GET "https://api.appeeky.com/v1/search?q=1617391485" \
-H "X-API-Key: YOUR_API_KEY"
Response — Keyword Search
{
"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:
{
"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) |
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.
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 |
