curl --request POST \
--url https://api.appgoat.ai/v1/watches \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"kind": "app",
"app": "com.spotify.music",
"countries": [
"us",
"de"
]
}
'{
"data": {
"id": 123,
"kind": "app",
"name": "<string>",
"store": "apple",
"app": {
"store": "apple",
"app_id": "<string>",
"title": "<string>",
"icon_url": "<string>",
"developer_name": "<string>"
},
"competitors": [
{
"store": "apple",
"app_id": "<string>",
"title": "<string>",
"icon_url": "<string>",
"developer_name": "<string>"
}
],
"terms": [
"<string>"
],
"keywords": [
{
"id": 123,
"term": "<string>",
"store": "apple",
"country": "<string>",
"ranked_at": "2023-11-07T05:31:56Z"
}
],
"countries": [
"<string>"
],
"event_types": [
"new_version"
],
"settings": {
"significance": 0.5,
"rank_move": 5,
"keyword_top_n": 10,
"chart_top_n": 100,
"rating_drop": 0.1,
"spike_factor": 3,
"email_digest": true,
"depth": 123,
"cadence_minutes": 123
},
"active": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"meta": {
"credits_used": 123,
"credits_remaining": 123,
"request_id": "<string>",
"freshness": {
"fetched_at": "2023-11-07T05:31:56Z",
"age_seconds": 123,
"stale": true,
"refreshing": true,
"job_id": "<string>"
},
"next_cursor": "<string>",
"store": "apple",
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "invalid_param",
"message": "limit must be ≤ 100",
"hint": "Fix the parameter and retry.",
"docs": "https://appgoat.ai/docs/errors#invalid_param",
"param": "limit"
}
}{
"error": {
"code": "invalid_param",
"message": "<string>",
"hint": "<string>",
"docs": "<string>",
"param": "<string>"
}
}{
"error": {
"code": "invalid_param",
"message": "<string>",
"hint": "<string>",
"docs": "<string>",
"param": "<string>"
}
}Watches & events
Create watch
Use this when the user wants to be told about changes ("tell me when a competitor updates", "alert me when my
rating drops", "track my ranks for these keywords"). Kinds:
- `app` { app }: new versions, metadata / price changes, featuring, rating drops, review and ratings spikes,
chart entries for that app.
- `competitor_set` { app?, competitors[] }: the same for every app in the set (your own `app` optional).
- `keyword` { terms[], store, app? }: search-rank moves of `app` for each term (`rank_change`) and new apps in
the top N (`keyword_entrant`).
Watched apps (competitors included) count against `limits.watches`; keyword watches use one keyword slot per
term × store × country (`limits.keywords`). Exceeding either returns 402 plan_limit and changes nothing.
Watched apps are refreshed daily. Events appear at `GET /v1/events` and go to your webhooks.
POST
/
watches
curl --request POST \
--url https://api.appgoat.ai/v1/watches \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"kind": "app",
"app": "com.spotify.music",
"countries": [
"us",
"de"
]
}
'{
"data": {
"id": 123,
"kind": "app",
"name": "<string>",
"store": "apple",
"app": {
"store": "apple",
"app_id": "<string>",
"title": "<string>",
"icon_url": "<string>",
"developer_name": "<string>"
},
"competitors": [
{
"store": "apple",
"app_id": "<string>",
"title": "<string>",
"icon_url": "<string>",
"developer_name": "<string>"
}
],
"terms": [
"<string>"
],
"keywords": [
{
"id": 123,
"term": "<string>",
"store": "apple",
"country": "<string>",
"ranked_at": "2023-11-07T05:31:56Z"
}
],
"countries": [
"<string>"
],
"event_types": [
"new_version"
],
"settings": {
"significance": 0.5,
"rank_move": 5,
"keyword_top_n": 10,
"chart_top_n": 100,
"rating_drop": 0.1,
"spike_factor": 3,
"email_digest": true,
"depth": 123,
"cadence_minutes": 123
},
"active": true,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"meta": {
"credits_used": 123,
"credits_remaining": 123,
"request_id": "<string>",
"freshness": {
"fetched_at": "2023-11-07T05:31:56Z",
"age_seconds": 123,
"stale": true,
"refreshing": true,
"job_id": "<string>"
},
"next_cursor": "<string>",
"store": "apple",
"warnings": [
"<string>"
]
}
}{
"error": {
"code": "invalid_param",
"message": "limit must be ≤ 100",
"hint": "Fix the parameter and retry.",
"docs": "https://appgoat.ai/docs/errors#invalid_param",
"param": "limit"
}
}{
"error": {
"code": "invalid_param",
"message": "<string>",
"hint": "<string>",
"docs": "<string>",
"param": "<string>"
}
}{
"error": {
"code": "invalid_param",
"message": "<string>",
"hint": "<string>",
"docs": "<string>",
"param": "<string>"
}
}Authorizations
Create a key at https://dash.appgoat.ai.
Body
application/json
Available options:
app, keyword, competitor_set Any {app} input. app: required; competitor_set: your own app (optional); keyword: the app whose ranks to report (optional).
competitor_set only.
Maximum array length:
50keyword only (or term).
Maximum array length:
500keyword watches without app (default both); also disambiguates app inputs.
Available options:
apple, play, both null = every type of the kind.
App / competitor_set watches: new_version (version + release notes), metadata_change (title, subtitle,
description, screenshots, icon, category…; payload.changes), price_change (price or in-app purchases),
featured (Editors' Choice, featuring, badges), in_app_event, installs_milestone (Play install bucket),
rating_drop (7-day drop ≥ settings.rating_drop), ratings_spike / review_spike (day count ≥
settings.spike_factor × the 14-day average), negative_review_spike (negative reviews per topic),
chart_enter / chart_leave (crossing the top settings.chart_top_n). Keyword watches: rank_change (the
watch's app moved ≥ settings.rank_move, or entered / left the ranking), keyword_entrant (new apps in the
top settings.keyword_top_n).
Available options:
new_version, metadata_change, price_change, featured, in_app_event, installs_milestone, rating_drop, ratings_spike, review_spike, negative_review_spike, chart_enter, chart_leave, rank_change, keyword_entrant Show child attributes
Show child attributes