AI 답변에서 내 브랜드가 빠진 지점을 짚어 줘요

Citation Analysis가 AI 답변이 참고한 페이지와 내 브랜드의 위치, 내 사이트부터 시작하는 할 일까지 보여 줘요.

달라진 점

• queries: 엔진이 실행한 검색과 그 검색으로 찾은 페이지를 함께 담습니다.
• sources: 엔진이 검색해 가져온 모든 페이지를 담습니다. cited로 인용 여부를 나누고, 검색 position, 엔진이 인용했다고 밝힌 구절, 페이지가 언급한 브랜드, 페이지를 누가 관리하는지 알려 주는 channel(내 사이트, 다른 브랜드, 매체, 쇼핑몰, 리뷰 플랫폼, 커뮤니티, 영상, 소셜, 블로그 플랫폼, 백과사전)이 붙습니다.
• brands: 내 브랜드, 경쟁사, 답변이 언급한 모든 브랜드를 답변에 나온 순서로 담고, 각 브랜드를 언급한 인용 페이지와 검색된 페이지를 연결합니다.
• visibility: 내 브랜드가 도달한 단계입니다. 답변에 언급됨부터 읽은 페이지 어디에도 없음까지 나뉩니다.
• actions: 할 일을 내가 직접 할 수 있는 순서로 담습니다. 내 페이지가 먼저, 직접 올릴 수 있는 플랫폼이 다음, 매체 제안이 마지막입니다. 항목마다 구체적인 steps와 근거 페이지가 붙습니다.
• insights: 인용 페이지들의 공통점(채널, 형식, 최신성, 비교 기준)과 내 브랜드의 위치를 짚고, 근거가 된 페이지와 링크를 밝힙니다.

POST /v1/citation-analysis의 응답에 version: 4와 위 필드가 새로 담깁니다. links는 형식이 그대로이고, 인사이트마다 linkIds와 함께 근거 페이지 sourceIds가 붙습니다. 이번 변경 전에 저장된 결과는 저장된 형식 그대로 유지됩니다. 이제 이름이 Citation Analysis예요. /v1/source-influence와 /v1/geo-audit, taskType SOURCE_INFLUENCE와 GEO_AUDIT, include.sourceInfluence와 include.geoAudit는 그대로 동작하고, 응답에는 /v1/citation-analysis, CITATION_ANALYSIS, citationAnalysis가 쓰입니다.

동작 방식

taskId를 보내면 엔진이 검색어와 검색된 페이지를 공개하는 경우(ChatGPT, Google AI Overview) 답변 태스크에서 그대로 가져옵니다. queries와 cited: false인 citations로 직접 보낼 수도 있습니다. 다른 엔진은 인용된 페이지만 담습니다.

추천은 주로 제3자 페이지에서 나옵니다. 저희가 살펴본 ChatGPT 답변에서 엔진은 페이지를 중앙값 20개 검색해 3개를 인용했고, 추천된 브랜드의 자사 사이트는 16%만 검색되고 6.8%만 인용됐습니다. 할 일은 이 흐름을 따라 내가 직접 할 수 있는 일부터 정렬됩니다.

• improve_page: 엔진이 검색하고도 지나친 내 페이지, 또는 인용됐는데 답변에 내 브랜드가 빠진 페이지입니다. 인용된 페이지처럼 질문에 답하도록 무엇을 더할지 알려 줍니다.
• publish_page: 내 페이지가 인용되지 않은 검색에 맞춰, 인용된 페이지를 본뜬 새 페이지 기획안을 줍니다. 페이지 유형, 제목 형식, 섹션, 보여 줄 근거, 날짜가 담깁니다.
• post_on_platform: 경쟁사가 나오는 쇼핑몰, 리뷰 플랫폼, 커뮤니티, 영상, 소셜 페이지입니다. 상품 정보 채우기, 실제 고객에게 리뷰 요청하기, 브랜드 담당자임을 밝히고 답하기 같은 단계를 줍니다.
• pitch_publisher: 매체만 고칠 수 있는 인용 기사입니다. 매체에 무엇을 보낼지 알려 줍니다.

모든 연결은 답변의 내용을 어느 페이지가 담고 있는지 보여 주고, 할 일마다 근거가 된 페이지를 정확히 가리킵니다. not_found 단계는 저희가 읽은 페이지에 브랜드가 나오지 않았다는 뜻입니다. brand를 보내면 visibility와 actions를 받고, brandDomains와 brandAliases를 더하면 자사 페이지와 다른 이름까지 함께 셉니다.

이렇게 활용하세요

• 내 사이트부터 시작합니다. 엔진이 지나친 페이지를 고치거나, 인용된 페이지를 본뜬 새 페이지를 기획합니다.
• 경쟁사가 보이는 상품 페이지와 커뮤니티 글을 쇼핑몰, 커뮤니티 담당자에게 넘깁니다.
• 답변이 가져간 페이지와 구절을 근거로 매체에 제안합니다.

요청 보내기

API 키를 Authorization 헤더에 넣어 요청을 보냅니다.

curl -X POST https://api.querying.ai/v1/citation-analysis \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "…",
    "brand": "Blueair",
    "competitors": ["Coway", "Levoit"],
    "brandDomains": ["blueair.com"]
  }'

요청 필드

taskIdstring필수

완료된 내 답변 태스크의 ID입니다. 그 답변과 인용 페이지가 answer, citations가 됩니다.

brandstring

내 브랜드 이름입니다. 보내면 결과에 visibility와 actions가 더해집니다.

competitorsarray

답변과 페이지에서 함께 살펴볼 경쟁사 이름입니다.

brandDomainsarray

내 사이트의 호스트 이름 최대 10개입니다. 예: coway.com. 이 사이트의 페이지는 own으로 표시됩니다.

brandAliasesarray

브랜드의 다른 이름 최대 10개입니다. 제품 라인이나 현지 표기를 넣습니다.

citations[].citedboolean

기본값 true. 엔진이 검색했지만 인용하지 않은 페이지는 false로 보내고, 있으면 position과 query도 넣습니다.

countrystring

인용 페이지를 읽을 국가입니다. 기본값 US.

webhook.urlstring

서버의 HTTPS 주소입니다. 태스크가 끝나는 즉시 결과를 이 주소로 보냅니다.

idempotencyKeystring

요청에 붙이는 고유 ID입니다. 키 하나는 계정에서 태스크 하나를 만들므로, 다시 보내도 태스크는 하나로 유지됩니다.

응답

완료된 태스크는 이런 형태입니다. 길이를 줄여 보여 드립니다.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "CITATION_ANALYSIS",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": "…", "creditsCharged": "…" },
  "response": {
    "version": 4,
    "answer": "The best-reviewed air purifiers depend on whether you …",
    "queries": [
      {
        "id": "q0",
        "text": "best air purifiers 2026 reviews independent testing …",
        "sourceIds": ["s0", "s1", "s2", "…", "s20"]
      }
    ],
    "sources": [
      {
        "id": "s13",
        "url": "https://www.blueair.com/products/blue-pure-211i-max",
        "domain": "blueair.com",
        "channel": "own",
        "cited": false,
        "position": 14,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [],
        "brandIds": ["b0"],
        "own": true,
        "paragraphs": []
      },
      {
        "id": "s14",
        "url": "https://www.target.com/p/levoit-core-300-air-…",
        "domain": "target.com",
        "channel": "retailer",
        "cited": true,
        "position": 15,
        "queryIds": ["q0"],
        "publishedAt": null,
        "citedText": [
          "A compact, straightforward option with a 4.6/5 rating …"
        ],
        "brandIds": ["b2"],
        "own": false,
        "paragraphs": [
          {
            "id": "s14p1",
            "text": "Levoit Core 300 Air Purifier White … $99.99 …"
          }
        ]
      },
      "…"
    ],
    "brands": [
      {
        "id": "b0",
        "name": "Blueair",
        "role": "target",
        "rank": 2,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s11"],
        "retrievedSourceIds": ["s5", "s6", "s8", "s9", "s13"],
        "ownSourceIds": ["s11", "s13"]
      },
      {
        "id": "b1",
        "name": "Coway",
        "role": "competitor",
        "rank": 1,
        "answerRanges": ["…"],
        "citedSourceIds": ["s1", "s3", "s4", "s7"],
        "retrievedSourceIds": ["s0", "s5", "s6", "s9", "s10", "s18"],
        "ownSourceIds": []
      },
      {
        "id": "b2",
        "name": "Levoit",
        "role": "competitor",
        "rank": 3,
        "answerRanges": ["…"],
        "citedSourceIds": ["s3", "s7", "s14"],
        "retrievedSourceIds": ["s6", "s15", "s16"],
        "ownSourceIds": []
      },
      "…"
    ],
    "links": [
      {
        "id": "l40",
        "paragraphId": "s14p1",
        "answerRanges": ["…"],
        "explanation": "Lists the Levoit Core 300 at $99.99, …"
      },
      "…"
    ],
    "visibility": {
      "brandId": "b0",
      "stage": "mentioned",
      "rank": 2,
      "answerBrands": 5
    },
    "actions": [
      {
        "id": "a0",
        "type": "improve_page",
        "control": "owned",
        "priority": 1,
        "summary": "Update Blueair’s site with a current, …",
        "steps": [
          "Add a page on best air purifiers in 2026 that covers …",
          "Include Blueair models in direct comparisons using published …",
          "…"
        ],
        "sourceIds": ["s13"],
        "brandIds": ["b0"],
        "queryIds": ["q0"],
        "linkIds": []
      },
      {
        "id": "a1",
        "type": "post_on_platform",
        "control": "platform",
        "priority": 2,
        "summary": "Improve Blueair’s Target product listing with …",
        "steps": [
          "Ensure the Blueair listing clearly states the model, current …",
          "…",
          "Keep product details current and invite genuine purchasers to …"
        ],
        "sourceIds": ["s14"],
        "brandIds": ["b2"],
        "queryIds": ["q0"],
        "linkIds": ["l40"]
      },
      "…"
    ],
    "insights": [
      {
        "summary": "Blueair’s second-place position is reflected in …",
        "sourceIds": ["s1", "s3", "s11"],
        "linkIds": ["l1", "l12", "l36"]
      },
      "…"
    ]
  }
}

task.statusstring

QUEUED, PROCESSING을 거쳐 답변과 함께 COMPLETED로, 또는 error와 함께 FAILED로 끝납니다.

credits.creditsChargedinteger

끝난 태스크에 청구된 크레딧입니다. 실패한 태스크는 0입니다.

response.versionnumber

결과 형식입니다. 검색어, 검색된 페이지, 브랜드, 할 일을 담는 분석은 4입니다.

response.answerstring

보낸 답변 그대로입니다. 모든 구간은 이 텍스트의 UTF-16 오프셋입니다.

response.queriesarray

엔진이 실행한 검색입니다. 각각 id, 검색어 text, 그 검색으로 찾은 sourceIds가 있습니다.

response.sourcesarray

엔진이 검색해 가져온 모든 페이지입니다. cited로 인용 여부를 구분하고, channel은 페이지를 누가 관리하는지 알려 줍니다(own, brand, editorial, retailer, review_platform, community, video, social, blog_platform, reference). position, queryIds, citedText, brandIds, own도 붙습니다. 인용된 페이지에는 paragraphs가 담깁니다.

response.brandsarray

내 브랜드, 경쟁사, 답변이 언급한 브랜드입니다. 각각 role, 답변 속 rank, answerRanges, 그 브랜드를 언급한 인용 페이지와 검색된 페이지가 있습니다.

response.linksarray

링크마다 문단 하나와 그 문단이 대응하는 answerRanges, 한 문장 explanation을 짝지어 줍니다.

response.visibilityobject

내 브랜드가 어디까지 갔는지입니다. stage는 mentioned, on_cited_page, on_retrieved_page, not_found 중 하나이고 rank, answerBrands가 함께 옵니다. brand를 보내지 않으면 null.

response.actionsarray

할 일을 priority 순으로 담습니다. 내 사이트에서 하는 owned 작업(improve_page, publish_page)이 먼저, 플랫폼에 올리는 platform 작업(post_on_platform)이 다음, 매체에 제안하는 outreach(pitch_publisher)가 마지막입니다. 각각 control, summary, 1~5개의 steps와 근거가 된 출처, 브랜드, 검색어, 링크가 붙습니다. brand를 보내지 않으면 비어 있습니다.

response.insightsarray

인용 페이지들의 공통점과 내 브랜드의 위치를 짧게 읽어 낸 내용으로, 최대 4개입니다. 각각 근거 페이지를 sourceIds로, 근거 링크를 linkIds로 밝힙니다.

결과 받기

요청하면 status가 QUEUED인 태스크가 바로 돌아옵니다. status가 COMPLETED나 FAILED가 될 때까지 GET /v1/async/task/{id}로 조회하거나, webhook.url을 넣어 같은 task, credits, response를 서버로 받으세요. 결과는 태스크가 끝난 뒤 24시간 동안 조회됩니다.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

요금

요금은 그대로입니다. 분석을 시작할 때 크레딧을 예약하고, 끝나면 정산합니다.