# Get market overview

Read who is winning one App Store storefront: the market pulse, the advertiser, viral and search-owner boards, the hottest and widest-open searches, and typed findings.

## Contract status

Preview contract: these routes and tools are implemented in the shared contract, but the public host, customer API access and OAuth flow have not been deployment verified.

## Endpoint: GET /v1/market/overview

- Method: `GET`
- Path: `/v1/market/overview`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_market_overview`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | query | ^[a-z]{2}$ | no | Apple storefront as two lowercase letters. Defaults to us. |

## Known errors

- 400 invalid_request for an unknown query parameter or a country that is not two lowercase letters.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing context:read scope or unavailable preview access.
- 429 rate_limited; wait for the Retry-After seconds, then send the same request again.

## Request

Send country as a query parameter. Unknown parameters are rejected. This GET never starts collection.

```
curl --get 'https://api.peekpanda.com/v1/market/overview' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal' \
  --data-urlencode 'country=us'
```

## Response

The response includes the country, the chart day with how many days of chart history exist, eight weekly dates, the market pulse, three boards, two search lists, typed findings and the suspects. The example uses observations from the US storefront on 10 September 2026, trimmed to one or two rows per list.

```
{
  "country": "us",
  "chart": {
    "day": "2026-09-10",
    "previousDay": "2026-09-09",
    "historyDays": 6
  },
  "weeks": [
    "2026-07-20",
    "2026-07-27",
    "2026-08-03",
    "2026-08-10",
    "2026-08-17",
    "2026-08-24",
    "2026-08-31",
    "2026-09-07"
  ],
  "pulse": {
    "paid": {
      "totalAds": 905,
      "liveAds": 830,
      "advertisers": 61,
      "startedLast7Days": 122,
      "longestDaysLive": 332,
      "weeklyStarts": [
        26,
        55,
        73,
        38,
        72,
        118,
        126,
        67
      ],
      "weeklyAdvertisers": [
        2,
        3,
        5,
        1,
        2,
        7,
        3,
        1
      ]
    },
    "organic": {
      "posts": 4879,
      "matchedPosts": 1397,
      "matchedApps": 699,
      "weeklyFound": [
        0,
        4,
        1,
        106,
        156,
        98,
        103,
        51
      ],
      "viewsCountedAt": "2026-05-29T00:00:00.000Z"
    },
    "keywords": {
      "rankedKeywords": 2285,
      "popularityTerms": 33039,
      "storefronts": 10
    }
  },
  "boards": {
    "advertisers": [
      {
        "storeId": "6480417616",
        "name": "Cal AI - Calorie Tracker",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/a1/74/2f/a1742f0e-6092-1e6c-38a9-135fd674f189/AppIcon-0-0-1x_U007ephone-0-1-85-220.png/128x128bb.png",
        "categoryName": "Health & Fitness",
        "liveAds": 95,
        "totalAds": 95,
        "startedLast7Days": 30,
        "medianDaysLive": 23,
        "longestDaysLive": 149,
        "videoShare": 0.905,
        "topCallToAction": "Learn more",
        "placement": {
          "rank": 6,
          "previousRank": 7,
          "chartType": "free",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "day": "2026-09-10"
        }
      }
    ],
    "viral": [
      {
        "storeId": "6759000863",
        "name": "Cheater Buster : AI Checker",
        "iconUrl": null,
        "categoryName": "Utilities",
        "matchedPosts": 6,
        "views": 275617771,
        "medianViews": 41073742,
        "bestPostViews": 82900000,
        "placement": null
      },
      {
        "storeId": "529479190",
        "name": "Clash of Clans",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/d7/af/ca/d7afca1f-0b51-4cc1-7e7f-b0fba87e3739/AppIcon-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png",
        "categoryName": "Games",
        "matchedPosts": 1,
        "views": 146800000,
        "medianViews": 146800000,
        "bestPostViews": 146800000,
        "placement": {
          "rank": 25,
          "previousRank": 33,
          "chartType": "grossing",
          "categoryId": "6014",
          "categoryName": "Games",
          "day": "2026-09-10"
        }
      }
    ],
    "searchOwners": [
      {
        "storeId": "389801252",
        "name": "Instagram",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/5a/18/99/5a189914-fa88-fab3-7ce2-506a624d2fbf/Prod-0-0-1x_U007epad-0-1-0-sRGB-85-220.png/128x128bb.png",
        "categoryName": "Photo & Video",
        "ranked": 328,
        "top10": 197,
        "top3": 86,
        "placement": {
          "rank": 2,
          "previousRank": 2,
          "chartType": "free",
          "categoryId": "6008",
          "categoryName": "Photo & Video",
          "day": "2026-09-10"
        }
      }
    ]
  },
  "searches": {
    "hottest": [
      {
        "query": "instagram",
        "popularity": 100,
        "previousPopularity": 100,
        "difficulty": 100,
        "rankingApps": 148,
        "leader": {
          "storeId": "389801252",
          "name": "Instagram",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/5a/18/99/5a189914-fa88-fab3-7ce2-506a624d2fbf/Prod-0-0-1x_U007epad-0-1-0-sRGB-85-220.png/128x128bb.png"
        }
      }
    ],
    "wideOpen": [
      {
        "query": "empower",
        "popularity": 69,
        "difficulty": 0,
        "opportunity": 69,
        "rankingApps": 184,
        "leader": {
          "storeId": "1454849875",
          "name": "Empower - Your ride, your way",
          "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/02/f6/b9/02f6b9f2-104b-e30c-5b04-2e004077a347/AppIconPassenger-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png"
        }
      }
    ]
  },
  "findings": {
    "climbingAndBuying": [
      {
        "storeId": "6480417616",
        "name": "Cal AI - Calorie Tracker",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/a1/74/2f/a1742f0e-6092-1e6c-38a9-135fd674f189/AppIcon-0-0-1x_U007ephone-0-1-85-220.png/128x128bb.png",
        "categoryName": "Health & Fitness",
        "placement": {
          "rank": 6,
          "previousRank": 7,
          "chartType": "free",
          "categoryId": "6013",
          "categoryName": "Health & Fitness",
          "day": "2026-09-10"
        },
        "startedLast7Days": 30,
        "liveAds": 95
      }
    ],
    "topTenUncollected": [
      {
        "storeId": "555376968",
        "name": "ESPN Fantasy Sports & More",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/fc/c8/f1/fcc8f1f5-9a4d-1a40-59e7-fae3fc7db2c8/AppIcon-0-0-1x_U007epad-0-11-0-85-220.png/128x128bb.png",
        "categoryName": "Sports",
        "rank": 2,
        "chartType": "free"
      }
    ],
    "newEntrants": [
      {
        "storeId": "6760173601",
        "name": "Muse from Meta",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/bf/06/f7/bf06f70f-8230-7065-5096-3d89145e18cf/HatchAppIconPublic-0-0-1x_U007ephone-0-1-0-sRGB-0-85-220.png/128x128bb.png",
        "categoryName": "Productivity",
        "rank": 4,
        "hasAds": false,
        "hasOrganic": false,
        "hasKeywords": false
      }
    ],
    "viralNotBuying": [
      {
        "storeId": "6759000863",
        "name": "Cheater Buster : AI Checker",
        "iconUrl": null,
        "categoryName": "Utilities",
        "matchedPosts": 6,
        "views": 275617771
      }
    ],
    "buyingNotCharting": [
      {
        "storeId": "1018368216",
        "name": "Cantina: AI Video & Characters",
        "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple211/v4/2a/78/80/2a78801f-f10f-78d8-d99d-9701b44edfa2/AppIcon-0-0-1x_U007ephone-0-1-0-sRGB-85-220.png/128x128bb.png",
        "categoryName": "Photo & Video",
        "liveAds": 30,
        "placement": {
          "rank": 13,
          "previousRank": 10,
          "chartType": "free",
          "categoryId": "6008",
          "categoryName": "Photo & Video",
          "day": "2026-09-10"
        }
      }
    ]
  },
  "suspects": [
    {
      "storeId": "341232718",
      "name": "MyFitnessPal: Calorie Counter",
      "iconUrl": "https://is1-ssl.mzstatic.com/image/thumb/Purple221/v4/3b/97/aa/3b97aa91-aa9d-d66d-e531-8cdef051e137/AppIcon-0-0-1x_U007emarketing-0-8-0-85-220.png/128x128bb.png",
      "categoryName": "Health & Fitness",
      "boards": [
        "chart",
        "paid",
        "organic",
        "search"
      ],
      "placement": {
        "rank": 1,
        "previousRank": 1,
        "chartType": "grossing",
        "categoryId": "6013",
        "categoryName": "Health & Fitness",
        "day": "2026-09-10"
      },
      "paid": {
        "liveAds": 19,
        "startedLast7Days": 2
      },
      "organic": {
        "matchedPosts": 1,
        "views": 342500
      },
      "keywords": {
        "top10": 45
      }
    }
  ]
}

```

## Source

Chart placements come from dated public App Store chart observations. chart.historyDays says how much chart history exists, so movement is day over day, not a trend. Paid ads are collected per chosen app, so an app without ads has not been collected. Organic posts are matched by product name, not account ownership, and their views are as last counted. pulse.organic.viewsCountedAt says when. Keyword positions are observed App Store search result positions, not search volume.

## Refresh

This GET reads stored evidence and never calls Apple or an advertising library. Keyword and organic aggregates are precomputed off the request path, and the dates in the payload say how fresh each stream is.

## Rate limits

Market reads share the standard read budget of 60 requests per minute with every other PeekPanda read. During the preview the count is kept per client network address, not per plan, and it resets at the end of each one-minute window. A 429 response carries Retry-After when the server can say how long to wait: wait that many seconds, then send the same request again. Peak and Panda quotas for these reads are not enforced yet, and stored reads do not use your refresh allowance.

## Bounded lists

This read has no cursor. Each board holds at most 15 apps and each search list at most 20 queries. Every weekly series has exactly 8 Monday-start weeks, oldest first, and the last one is the current, partial week. Findings and suspects list only the apps that meet their rule, so any of them can be empty. A suspect sits on at least 3 of the four boards: chart, paid, organic and search.