Market Share Trends Over Time

Tracks how each brand's weighted market presence evolves over time, showing shifts in competitive dynamics and market leadership. This endpoint shows share of voice trends by time period, revealing which brands are gaining or losing market presence. Unlike simple mention rates, this captures both visibility and prominence changes. Essential for tracking competitive shifts, measuring long-term brand building efforts, and identifying market disruption. **When to use:** User wants to track market share evolution, identify competitive shifts over time, measure brand building impact, analyze market dynamics, or detect emerging competitors. **Common user queries:** - "How has market share changed over time?" - "Show me share of voice trends" - "Track Nike's market dominance evolution" - "Which brands are gaining market share?" - "Display competitive dynamics over time" - "Has share of voice improved?" **Returns:** Array of brands with share of voice values by time period. Example: [{"brand": "Nike", "period": "2024-01-01", "share_of_voice": 0.42}, {"brand": "Nike", "period": "2024-01-08", "share_of_voice": 0.45}] Required permission: `read:analysis`.

GET /v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries

Market Share Trends Over Time

cURL

curl --request GET \
  --url https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries \
  --header 'Authorization: <api-key>'

import requests

url = "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_awareness/share_of_voice_timeseries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

200

[
  {
    "brand": "<string>",
    "share_of_voice": "<string>",
    "collection_date": "2023-12-25"
  }
]

Authorizations

Authorization · string · header · required

Path Parameters

analysis_id · string<uuid> · required

A UUID string identifying the analysis.

organization_id · string<uuid> · required

A UUID string identifying the organization.

workspace_id · string<uuid> · required

A UUID string identifying the workspace.

Query Parameters

brand · string

Filter by one specific brand.

brand__in · string

Filter by a list of brands. Values should be comma separated, without brackets or spaces

collection_date · string<date>

Filter by a collection date being equal to the specified date. YYYY-MM-DD format

collection_date__gt · string<date>

Filter by a collection date being greater than the specified date. YYYY-MM-DD format

collection_date__gte · string<date>

Filter by a collection date being greater than or equal the specified date. YYYY-MM-DD format

collection_date__lt · string<date>

Filter by a collection date being less than the specified date. YYYY-MM-DD format

collection_date__lte · string<date>

Filter by a collection date being less than or equal the specified date. YYYY-MM-DD format

country · string

Filter by one specific country.

country__in · string

Filter by a list of countries. Values should be comma separated, without brackets or spaces

format · enum<string>

Available options: csv, json

limit · integer

Limit number of results.

period · enum<string> · required

Interval of the timeseries.

Available options: day, month, week

persona · string

Filter by one specific persona.

persona__in · string

Filter by a list of personas. Values should be comma separated, without brackets or spaces

source · enum<string>

Filter by one specific source.

Available options: claude-3-5-sonnet, claude-4-5-sonnet, claude-4-6-sonnet, claude-4-sonnet, deepseek-chat, deepseek-reasoner, deepseek-v3.2-maas, gemini-1.5-pro, gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-grounded, gemini-2.5-flash-lite, gemini-3-flash-preview, google-ai-mode, gpt-3.5-turbo, gpt-4-turbo, gpt-4o, gpt-4o-mini-search, gpt-5, gpt-5.2, gpt-5.4-mini, meta-llama-3.1-70B-instruct-turbo, meta-llama-3.2-70B-instruct-turbo, meta-llama-3.3-70B-instruct-turbo, meta-llama-4-maverick, mistral-7B-instruct, perplexity-sonar, rufus

source__in · enum<string>

Filter by a list of sources. Values should be comma separated, without brackets or spaces

Available options: claude-3-5-sonnet, claude-4-5-sonnet, claude-4-6-sonnet, claude-4-sonnet, deepseek-chat, deepseek-reasoner, deepseek-v3.2-maas, gemini-1.5-pro, gemini-2.0-flash, gemini-2.5-flash, gemini-2.5-flash-grounded, gemini-2.5-flash-lite, gemini-3-flash-preview, google-ai-mode, gpt-3.5-turbo, gpt-4-turbo, gpt-4o, gpt-4o-mini-search, gpt-5, gpt-5.2, gpt-5.4-mini, meta-llama-3.1-70B-instruct-turbo, meta-llama-3.2-70B-instruct-turbo, meta-llama-3.3-70B-instruct-turbo, meta-llama-4-maverick, mistral-7B-instruct, perplexity-sonar, rufus

Response

200

application/json

brand · string · required

share_of_voice · string<decimal> · required

Pattern: ^-?\d{0,1}(?:\.\d{0,4})?$

collection_date · string<date> · required