serp-metrics

Compute the impression-weighted average SERP position for a set of query rows, alongside the plain arithmetic mean and the gap between them. The arithmetic mean lets a 3-impression query count as much as a 30,000-impression one; the weighted figure describes where a typical impression actually happened. A positive weighting_shift means your high-volume queries rank worse than the unweighted average suggests.

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Optional label for the row."
          },
          "position": {
            "type": "number",
            "description": "Average SERP position for the row, 1-based."
          },
          "impressions": {
            "type": "number",
            "description": "Impressions the row received."
          },
          "clicks": {
            "type": "number",
            "description": "Optional observed clicks, used to calibrate the curve."
          },
          "target_position": {
            "type": "number",
            "description": "Optional per-row target position, overriding the global target."
          }
        },
        "required": [
          "position",
          "impressions"
        ]
      },
      "description": "Query rows."
    }
  },
  "required": [
    "rows"
  ],
  "additionalProperties": false
}

Project how many clicks a set of query rows would earn at a target position instead of their current position, using a CTR curve THAT YOU SUPPLY. This server deliberately ships no built-in CTR table: every published average-CTR-by-position table is a third-party estimate over someone else's traffic, so applying one silently would disguise a guess as a measurement. Pass your own measured curve (Search Console clicks/impressions by position is the honest source). Positions between curve points are linearly interpolated; positions beyond the curve clamp to the last point rather than extrapolate, and are counted in clamped_row_count. If any row carries observed clicks, the output also reports how far the supplied curve is from your reality.

{
  "type": "object",
  "properties": {
    "rows": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Optional label for the row."
          },
          "position": {
            "type": "number",
            "description": "Average SERP position for the row, 1-based."
          },
          "impressions": {
            "type": "number",
            "description": "Impressions the row received."
          },
          "clicks": {
            "type": "number",
            "description": "Optional observed clicks, used to calibrate the curve."
          },
          "target_position": {
            "type": "number",
            "description": "Optional per-row target position, overriding the global target."
          }
        },
        "required": [
          "position",
          "impressions"
        ]
      },
      "description": "Query rows."
    },
    "ctr_curve": {
      "type": "object",
      "description": "Required. Map of position to click-through rate as a 0-1 fraction, e.g. {\"1\":0.28,\"2\":0.15,\"3\":0.10,\"10\":0.02}. Supply your own measured values.",
      "additionalProperties": {
        "type": "number"
      }
    },
    "target_position": {
      "type": "number",
      "description": "Target position applied to every row that does not carry its own."
    }
  },
  "required": [
    "rows",
    "ctr_curve"
  ],
  "additionalProperties": false
}

Compute share of voice across competing entities over a keyword set. Reports impression share always, and, if you supply a CTR curve, a weighted visibility share that accounts for the fact that an impression at position 1 is not worth an impression at position 9. Impression share is share of the supplied set only and says nothing about keywords you did not supply.

{
  "type": "object",
  "properties": {
    "entities": {
      "type": "array",
      "description": "One entry per competitor per keyword, or pre-aggregated per competitor.",
      "items": {
        "type": "object",
        "properties": {
          "entity": {
            "type": "string",
            "description": "Competitor name or domain."
          },
          "impressions": {
            "type": "number"
          },
          "position": {
            "type": "number",
            "description": "Average position, required only when a ctr_curve is supplied."
          }
        },
        "required": [
          "impressions"
        ]
      }
    },
    "ctr_curve": {
      "type": "object",
      "description": "Optional caller-supplied position-to-CTR map, for weighted visibility.",
      "additionalProperties": {
        "type": "number"
      }
    }
  },
  "required": [
    "entities"
  ],
  "additionalProperties": false
}