{
  "version": "dv-data-dictionary-v2",
  "documentationPath": "/learn/data-dictionary",
  "product": "all",
  "notes": [
    "DSI is a weather-derived index, not a clinical measure, sales prediction or audience size.",
    "Search outlooks describe a Sunday–Saturday week revised daily, not daily search predictions or counts.",
    "Dry skin and humidifier use different index scales; do not compare or add their indices.",
    "Google Trends metro areas differ from Census CBSA metros; no mapping to Census metro areas is approved.",
    "Search outlooks have no calibrated per-metro-area prediction intervals. Small differences may be noise.",
    "CSV blanks represent unavailable values, not zero. Producer-only fields are not customer CSV columns."
  ],
  "sections": [
    {
      "id": "dsi",
      "title": "Daily DSI forecast",
      "fields": [
        {
          "csv": "cbsa",
          "api": "cbsa",
          "meaning": "U.S. Census metro code.",
          "unit": "5-digit text",
          "example": "14460"
        },
        {
          "csv": "metro_name",
          "api": "metroName",
          "meaning": "Official metro name.",
          "unit": "text",
          "example": "Boston-Cambridge-Newton, MA-NH"
        },
        {
          "csv": "date",
          "api": "date",
          "meaning": "Forecast date.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-07"
        },
        {
          "csv": "lead_day",
          "api": "leadDay",
          "meaning": "Forecast day; 1 is the issue date.",
          "unit": "1–7",
          "example": "1"
        },
        {
          "csv": "forecast_confidence",
          "api": "forecastConfidence",
          "meaning": "Confidence label; reduced from day 6.",
          "unit": "standard / reduced",
          "example": "standard"
        },
        {
          "csv": "dsi",
          "api": "dsi",
          "meaning": "Modeled indoor drying stress on skin; higher means drier.",
          "unit": "index, 0–10",
          "example": "5.92"
        },
        {
          "csv": "dsi_low",
          "api": "dsiLow",
          "meaning": "Lower end of the forecast range.",
          "unit": "index, 0–10",
          "example": "4.88"
        },
        {
          "csv": "dsi_high",
          "api": "dsiHigh",
          "meaning": "Upper end of the forecast range.",
          "unit": "index, 0–10",
          "example": "7.17"
        },
        {
          "csv": "covered_population",
          "api": "coveredPopulation",
          "meaning": "Population covered by the metro forecast.",
          "unit": "people",
          "example": "4917438"
        }
      ]
    },
    {
      "id": "dsi-summary",
      "title": "Seven-day DSI summaries",
      "fields": [
        {
          "csv": "rank",
          "api": "rank",
          "meaning": "Rank within the requested sort; present only for ranked results.",
          "unit": "integer, 1 = highest",
          "example": "1"
        },
        {
          "csv": "cbsa",
          "api": "cbsa",
          "meaning": "U.S. Census metro code.",
          "unit": "5-digit text",
          "example": "14460"
        },
        {
          "csv": "metro_name",
          "api": "metroName",
          "meaning": "Official metro name.",
          "unit": "text",
          "example": "Boston-Cambridge-Newton, MA-NH"
        },
        {
          "csv": "first_date",
          "api": "firstDate",
          "meaning": "First date included in the summary.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-07"
        },
        {
          "csv": "last_date",
          "api": "lastDate",
          "meaning": "Last date included in the summary.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-13"
        },
        {
          "csv": "days",
          "api": "days",
          "meaning": "Number of daily values summarized.",
          "unit": "days",
          "example": "7"
        },
        {
          "csv": "mean7",
          "api": "mean7",
          "meaning": "Arithmetic mean of daily DSI values in this issue.",
          "unit": "index, 0–10",
          "example": "5.2"
        },
        {
          "csv": "peak_dsi",
          "api": "peak.dsi",
          "meaning": "Highest daily DSI.",
          "unit": "index, 0–10",
          "example": "6.2"
        },
        {
          "csv": "peak_date",
          "api": "peak.date",
          "meaning": "Date of the highest DSI; earliest date if tied.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-09"
        },
        {
          "csv": "excess_above_4",
          "api": "excessAbove4",
          "meaning": "Sum of max(DSI − 4, 0) across the forecast days.",
          "unit": "index-days above 4",
          "example": "8.4"
        },
        {
          "csv": "population_65plus",
          "api": "population65plus",
          "meaning": "Metro-wide population aged 65+, from 2023 ACS 5-year B01001.",
          "unit": "people; null if unavailable",
          "example": "100000"
        },
        {
          "csv": "exposure_65plus",
          "api": "exposure65plus",
          "meaning": "Cumulative excess above 4 multiplied by population aged 65+. Blank if population is unavailable.",
          "unit": "65+ person-index-days",
          "example": "840000"
        },
        {
          "csv": "trend_slope_per_day",
          "api": "trend.slopePerDay",
          "meaning": "Least-squares slope of daily DSI over the window.",
          "unit": "DSI per day",
          "example": "0.2"
        },
        {
          "csv": "trend",
          "api": "trend.label",
          "meaning": "Rising at slope ≥ 0.15/day; falling at ≤ −0.15/day; otherwise steady.",
          "unit": "rising / falling / steady",
          "example": "rising"
        }
      ]
    },
    {
      "id": "search",
      "title": "Dry skin and humidifier search outlooks",
      "fields": [
        {
          "csv": "Google Trends id",
          "api": "regionCode",
          "meaning": "Google Trends metro area identifier. Older exports use region_code or dma_code; API/MCP retains regionCode.",
          "unit": "3-digit text",
          "example": "501"
        },
        {
          "csv": "region_name",
          "api": "regionName",
          "meaning": "Google Trends metro area name. Producer files call this dma_name.",
          "unit": "text",
          "example": "New York"
        },
        {
          "csv": "target_week_start",
          "api": "targetWeek.start",
          "meaning": "Sunday starting the predicted week.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-04"
        },
        {
          "csv": "target_week_end",
          "api": "targetWeek.end",
          "meaning": "Saturday ending the predicted week.",
          "unit": "YYYY-MM-DD",
          "example": "2026-10-10"
        },
        {
          "csv": "weather_rank",
          "api": "weatherRank",
          "meaning": "Rank of weather effect across the full category outlook; retained after filtering.",
          "unit": "1 = largest rise",
          "example": "1"
        },
        {
          "csv": "predicted_search_index",
          "api": "predictedSearchIndex",
          "meaning": "Modeled weekly search interest on the category’s training scale; not search counts.",
          "unit": "index",
          "example": "89.69"
        },
        {
          "csv": "weather_search_change_pct",
          "api": "weatherChangePct",
          "meaning": "Modeled change versus normal weather: 100 × (weather_search_multiplier − 1).",
          "unit": "percent",
          "example": "7.99"
        },
        {
          "csv": "seasonal_planning_ratio",
          "api": "seasonalPlanningRatio",
          "meaning": "Predicted index divided by the Google Trends metro area’s average index; a different baseline from normal weather.",
          "unit": "ratio; 1 = average week",
          "example": "1.20"
        },
        {
          "csv": "extrapolation",
          "api": "extrapolation",
          "meaning": "True when dryness is outside the Google Trends metro area’s training range; interpret with greater caution.",
          "unit": "true / false",
          "example": "false"
        },
        {
          "csv": "dsi_population_coverage",
          "api": "dsiPopulationCoverage",
          "meaning": "Fraction of Google Trends metro area population covered by DSI weather inputs; not audience size.",
          "unit": "fraction, 0–1",
          "example": "0.92"
        }
      ]
    },
    {
      "id": "search-producer",
      "title": "Additional internal producer fields",
      "fields": [
        {
          "csv": "category",
          "api": "—",
          "meaning": "Search category in the producer artifact.",
          "unit": "dry_skin / humidifier",
          "example": "dry_skin"
        },
        {
          "csv": "dma_code",
          "api": "regionCode",
          "meaning": "Legacy producer name for the Google Trends identifier; customer CSV uses Google Trends id.",
          "unit": "3-digit text",
          "example": "501"
        },
        {
          "csv": "dma_name",
          "api": "regionName",
          "meaning": "Producer name for the Google Trends metro area name; customer CSV uses region_name.",
          "unit": "text",
          "example": "New York"
        },
        {
          "csv": "weather_search_multiplier",
          "api": "—",
          "meaning": "Expected interest relative to normal weather. 1.10 means +10%; 0.90 means −10%.",
          "unit": "ratio",
          "example": "1.10"
        },
        {
          "csv": "cohort_complete",
          "api": "—",
          "meaning": "Whether all required regions in the supported category cohort were produced.",
          "unit": "true / false",
          "example": "true"
        },
        {
          "csv": "prior_issue_change",
          "api": "—",
          "meaning": "Reserved change-from-prior-issue field. Currently required to be null; no usable change value or unit is defined.",
          "unit": "null; blank in CSV",
          "example": "blank"
        }
      ]
    }
  ],
  "signalGuidance": {
    "version": "dv-search-signal-guidance-v4",
    "attribution": {
      "source": "Google Trends",
      "sourceUrl": "https://trends.google.com/",
      "statement": "Historical search data source: Google Trends. Search outlooks are Dermal Vectors modeled estimates using historical search data and weather-derived DSI, not forecasts supplied by Google or Google Ads search volume."
    },
    "documentationPath": "/learn/data-dictionary#marketing-signals",
    "geography": "DSI forecasts use U.S. Census metro areas (5-digit CBSA codes); search forecasts use Google Trends metro areas (Google Trends ids). Their urban areas have different geographies and are not directly comparable. A shared city name does not establish matching boundaries or populations. Do not join, substitute or make paired local comparisons by name or code. No approved mapping is currently provided. Discuss complementary signals with each geography clearly identified, without implying they describe the same local population.",
    "signals": [
      {
        "field": "weatherChangePct",
        "csv": "weather_search_change_pct",
        "sort": "weather_change",
        "question": "Where does unusual dryness suggest a category messaging or timing opportunity?",
        "baseline": "Same Google Trends metro area and week with training-normal dryness features, retaining seasonality.",
        "interpretation": "Modeled percentage difference associated with dryness versus normal weather; not causal advertising lift."
      },
      {
        "field": "seasonalPlanningRatio",
        "csv": "seasonal_planning_ratio",
        "sort": "seasonal",
        "question": "Where is this week's expected category interest above the Google Trends metro area's average week?",
        "baseline": "The Google Trends metro area's arithmetic mean search index in model training.",
        "interpretation": "Includes both seasonality and weather. 1.20 means 20% above that Google Trends metro area's average week, not 20% weather lift."
      }
    ],
    "workflow": [
      "Identify the manager's category, markets and planning objective; clarify missing context before tailoring an action.",
      "Read get_product_dictionary and check available products with list_forecast_products; retrieve a current category outlook.",
      "For weather-related timing use sort=weather_change; for overall weekly interest use sort=seasonal. Show both signals together and explain the chosen baseline.",
      "Do not invent a composite score or significance threshold. The default top 10 is a shortlist selected by the requested sort, not the entire category universe.",
      "Cite issueId, targetWeek, category, Google Trends ids, selection scope and sorting metric; reuse that issue when comparing results.",
      "Propose a messaging, timing or geographic test. Ask for brand campaign performance, inventory and media costs before recommending spending changes; manager approval precedes campaign action."
    ],
    "examples": [
      {
        "label": "Illustration, not a live forecast",
        "weatherChangePct": 12,
        "seasonalPlanningRatio": 1.2,
        "explanation": "Both signals are above their baselines: consider a weather-relevant timing test; neither establishes incremental sales."
      },
      {
        "label": "Illustration, not a live forecast",
        "weatherChangePct": 0,
        "seasonalPlanningRatio": 1.2,
        "explanation": "An above-average seasonal week without an additional modeled dryness effect; use seasonal context rather than a weather-rise claim."
      },
      {
        "label": "Illustration, not a live forecast",
        "weatherChangePct": 12,
        "seasonalPlanningRatio": 0.8,
        "explanation": "Above normal-weather interest but still below the Google Trends metro area's average week; describe the relative increase without calling it a high overall opportunity."
      }
    ],
    "qualifications": [
      "Keep dry-skin and humidifier categories separate; their index scales cannot be compared or added.",
      "WeatherRank remains the category-wide weather rank, even in seasonal sorts or filtered results; it is not a confidence score.",
      "PredictedSearchIndex is not search counts, market size or audience size. Lower values alone do not justify campaign cuts.",
      "Flag extrapolation and explain dsiPopulationCoverage as weather-input coverage, not people searching or forecast confidence.",
      "There are no calibrated per-metro-area search prediction intervals; small differences may be noise. Do not infer significance from rank.",
      "These are Sunday-Saturday weekly outlooks revised daily, not daily search peaks. Do not merge Google Trends metro areas with Census DSI metros without a governed mapping.",
      "No causal weather, campaign, sales or ROI claim follows from these modeled associations. Missing brand context must remain explicit."
    ],
    "managerReport": [
      "Recommended signal and why it fits the question",
      "Google Trends metro areas, both signal values and their baselines",
      "Suggested test and required brand context",
      "Extrapolation, coverage and uncertainty qualifications",
      "Issue, category, week and selection scope"
    ]
  }
}