ASO: Keywords

Track keywords, pull daily ranking history + deltas, competitor trajectory, visibility score, suggestions, and digest settings.

Keywords are tracked per project + store + country. Tracking enrolls the keyword in Forvibe's periodic ranking capture so you can chart movement over time.

List tracked keywords

bash

GET /api/v1/projects/:projectId/keywords?store_type=appstore&country=US

# Scope: aso:read

Track a new keyword

bash

POST /api/v1/projects/:projectId/keywords
Content-Type: application/json

{
  "store_type": "appstore",
  "keyword": "focus timer",
  "country": "US",
  "language": "en",
  "search_volume": 65,
  "difficulty": 40
}

# Scope: aso:write
# 409 DUPLICATE if the same (project, store, country, keyword) already exists

Untrack a keyword

bash

DELETE /api/v1/keywords/:keywordId

# Scope: aso:write
# Returns: 204 No Content

Ranking history

bash

GET /api/v1/keywords/:keywordId/rankings?days=30

# Scope: aso:read
# Returns: { data: { tracked_keyword_id, keyword, store_type, country, window_days,
#   points: [{ snapshot_date, rank_position, rank_delta }, ...] } }
# rank_delta = previous_day_rank - rank (positive = improved)

Rankings overview (latest + change)

bash

GET /api/v1/projects/:projectId/keyword-rankings?store_type=appstore&country=US

# Scope: aso:read
# Returns: { data: [{ id, keyword, current_rank, rank_delta, best_rank, ... }, ...] }

Competitor trajectory

bash

GET /api/v1/keywords/:keywordId/competitor-trajectory?days=30

# Scope: aso:read
# Returns: { data: { keyword, own: [{snapshot_date, rank_position}], competitors: [{app_id, app_name, points}] } }

Optimization (visibility + metadata audit)

bash

GET /api/v1/projects/:projectId/optimization?store_type=appstore&country=US

# Scope: aso:read
# Returns: { data: { visibility: {score, status, trend}, summary: {keep, monitor, drop},
#   indexed: [{keyword, rank, verdict, reason}], opportunities: [...] } }

Suggestions (weekly, credit-free)

bash

GET /api/v1/projects/:projectId/suggestions?store_type=appstore&country=US

# Scope: aso:read
# Returns: { data: { keywords: [{keyword, reason}], competitors: [{app_id, app_name, reason}], generatedAt } }
# Pre-computed weekly from a deep store-listing analysis. Never consumes credits.

Daily digest settings

bash

GET /api/v1/projects/:projectId/notification-settings
# Scope: aso:read

PUT /api/v1/projects/:projectId/notification-settings
Content-Type: application/json

{
  "enabled": true,
  "frequency": "daily",
  "send_hour_local": 9,
  "timezone": "Europe/Istanbul"
}

# Scope: aso:write