> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Expansion 엔드포인트 선택하기

> Expansion API 를 위한 작업-엔드포인트 가이드 — 발견, 회사 상세, 시그널 피드, 비교, 지도, 레퍼런스 값 각각에 어떤 엔드포인트를 호출해야 하는지.

Expansion API 는 소수의 엔드포인트로 구성되며, 각각은 회사가 새로운 시장으로 어떻게 확장해 가는지에 대한 서로 다른 질문에 답합니다. 이 가이드는 **무엇을 하고 싶은지** 를 **어떤 엔드포인트를 호출해야 하는지** 로 연결해 주므로, 추측할 필요가 없습니다.

<Info>
  개념(스테이지, 시그널, 모멘텀, 신선도)에 처음이신가요? [Expansion 시그널이란?](/ko/knowledge-base/concepts/expansion-signals) 에서 시작하세요 — 이 가이드는 해당 개념을 이미 알고 있다고 가정하며 엔드포인트 선택에 집중합니다.
</Info>

## 작업별로 고르기

| 하고 싶은 것…                                                                               | 호출                                                                                           |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| 특정 시장으로 확장하는 **회사 찾기**(필터 또는 자연어 쿼리로)                                                  | [Expansion Search](/ko/api-reference/endpoint/expansions/market_lookup)                      |
| **시장 수준 KPI 및 흐름** 보기(스테이지별 건수, 상위 코리도)                                                | [Expansion Overview](/ko/api-reference/endpoint/expansions/dashboard)                        |
| **한 회사의 특정 시장 내 상태** 가져오기 — 스테이지, 진출 현황, 이력, 그리고 그 근거가 되는 시그널                          | [Company Expansion Detail](/ko/api-reference/endpoint/expansions/company_lookup)             |
| 회사의 시그널 이벤트에 대한 **풍부하고 기간 범위가 지정된 피드** 가져오기                                            | [Company Signal Events](/ko/api-reference/endpoint/expansions/company_pulse_events)          |
| 대상 회사에서 시드하여, 여러 회사의 확장을 나란히 **비교**                                                    | [Compare Company Expansions](/ko/api-reference/endpoint/expansions/company_compare)          |
| 이미 보유한 회사 집합(도메인, LinkedIn URL, 또는 ID)에 대해 **바로 렌더링 가능한 비교 지표**(시장 수, 모멘텀, 확장 점수) 가져오기 | [Batch Company Expansion Summaries](/ko/api-reference/endpoint/expansions/company_summaries) |
| **순위가 매겨진 회사/시장 포인트** 를 지도나 히트맵에 표시                                                    | [Expansion Rankings](/ko/api-reference/endpoint/expansions/company_markers)                  |
| **필터 및 enum 값**(스테이지, 시그널 유형, 신선도…) 해석                                                 | [Expansion Reference](/ko/api-reference/endpoint/expansions/types)                           |

## 엔드포인트 한눈에 보기

<CardGroup cols={2}>
  <Card title="Expansion Search" icon="magnifying-glass" href="/ko/api-reference/endpoint/expansions/market_lookup">
    발견용 엔드포인트입니다. 회사를 확장 스테이지, 신선도, 시장, 그리고 전체 회사 펌오그래픽 세트로 필터링하거나 — 자연어 `query` 를 전달하세요. 페이지네이션된 회사 목록.
  </Card>

  <Card title="Expansion Overview" icon="chart-simple" href="/ko/api-reference/endpoint/expansions/dashboard">
    시장 수준 집계: 스테이지별 건수, 상위 국경 간 흐름, 관심 회사 활동. 페이지네이션 없음 — 대시보드 스냅샷.
  </Card>

  <Card title="Company Expansion Detail" icon="building-magnifying-glass" href="/ko/api-reference/endpoint/expansions/company_lookup">
    한 시장 내 한 회사: 현재 스테이지, 점수, 진출 현황, 전환 이력, 그리고 이를 뒷받침하는 시그널. 시장별 스냅샷.
  </Card>

  <Card title="Company Signal Events" icon="timeline" href="/ko/api-reference/endpoint/expansions/company_pulse_events">
    여러 시그널 유형과 날짜 범위에 걸친 회사 시그널 이벤트의 풍부하고 페이지네이션된 피드. 활동 드릴다운.
  </Card>

  <Card title="Compare Company Expansions" icon="scale-balanced" href="/ko/api-reference/endpoint/expansions/company_compare">
    한 번의 호출로 여러 회사를 나란히, 주간 시그널 시계열과 선택적 피어 시딩과 함께. 비교 그리드를 위해 설계되었습니다.
  </Card>

  <Card title="Batch Company Expansion Summaries" icon="table" href="/ko/api-reference/endpoint/expansions/company_summaries">
    domain\_search\_id, 도메인, LinkedIn URL 을 임의로 조합해 해석한 뒤, Compare 와 동일한 데이터에 계산된 요약 블록을 더해 반환합니다 — 대상 회사도, 피어 시딩도 없습니다.
  </Card>

  <Card title="Expansion Rankings" icon="map-location-dot" href="/ko/api-reference/endpoint/expansions/company_markers">
    회사/시장 쌍의 가볍고 점수순으로 정렬된 목록 — 최소 필드, 페이지네이션 없음 — 빠른 지도 및 히트맵 렌더링용.
  </Card>
</CardGroup>

## "Detail" vs "Signal Events" — 어느 것을?

**둘 다 시그널을 다루기 때문에** 가장 흔히 혼동되는 지점입니다. 차이는 *스냅샷 vs 피드* 입니다:

|           | Company Expansion Detail                                      | Company Signal Events                                              |
| --------- | ------------------------------------------------------------- | ------------------------------------------------------------------ |
| **범위**    | 한 회사 × **한 시장**                                               | 한 회사, **모든 해외 시장** 에 걸쳐                                            |
| **시장**    | `country_code` 로 **단일 시장**, 또는 `is_all_markets` 로 회사 전체를 한 번에 | 기본적으로 **모든 해외 시장**(본국 시장 제외); `country_codes`(배열)로 특정 시장으로 좁힘      |
| **반환**    | 스테이지, 점수, 진출 현황, 이력 **+ 뒷받침 시그널**                             | **풍부한 시그널 이벤트**(근거 URL, 채용 명단, 라벨)                                 |
| **시간**    | 현재 위치                                                         | 직접 선택하는 **날짜 범위**(`window_days` — 기본 90 — 또는 `transitioned_dates`) |
| **형태**    | 구조화된 스냅샷 객체                                                   | 페이지네이션된 이벤트 피드("더 보기")                                             |
| **사용 시점** | "이 회사의 **특정 한** 시장 내 상태는 어떻고, 그 이유는?"                         | "이 회사의 확장을 이끄는 **모든** 시장의 전체 흐름을 보여줘"                              |

<Tip>
  **대부분의 통합에는 Company Expansion Detail 만 있으면 됩니다** — 이미 한 시장 내 회사의 스테이지를 뒷받침하는 시그널을 반환하기 때문입니다. 풍부하고 필터 가능하며 기간 범위가 지정된 이벤트 스트림(예: 활동 타임라인 UI 구축)이 특별히 필요할 때 **Company Signal Events** 를 사용하세요.
</Tip>

## "Compare" vs "Summaries" — 어느 것을?

두 엔드포인트 모두 동일한 회사별 확장 데이터를 나란히 반환합니다. 차이는 *식별자와 사용 맥락*입니다:

|            | Compare Company Expansions                       | Batch Company Expansion Summaries                              |
| ---------- | ------------------------------------------------ | -------------------------------------------------------------- |
| **입력**     | `domain_search_id` 만                             | `domain_search_id`, `domain`, `linkedin_url` 임의 조합             |
| **피어 시딩**  | 선택적, `seed_target` 을 통해                          | 없음 — 각 회사는 독립적입니다                                              |
| **계산된 집계** | 없음(시장 수/모멘텀/점수를 직접 계산해야 함)                       | 회사별 `summary` 블록 포함(활성/신규 시장 수, 모멘텀, 확장 점수, 단계 구성)             |
| **사용 시점**  | 이미 해석된 ID가 있고 하나의 대상 회사에 대해 비교 가능한 피어를 시드하고 싶을 때 | 도메인이나 LinkedIn URL로 주어진 회사가 있고 한 번의 호출로 바로 렌더링 가능한 비교 지표를 원할 때 |

<Tip>
  **대상 회사를 중심으로 경쟁사 벤치마킹 그리드를 만드시나요?** **Compare** 에 `seed_target` 을 전달해 피어를 자동으로 선택하세요. **이미 회사 집합**(관심 목록, CRM 임포트, 도메인 목록)**이 있고 숫자만 필요하신가요?** **Batch Company Expansion Summaries** 를 사용하세요 — 모멘텀/점수 계산을 클라이언트 측에서 다시 구현할 필요가 없습니다.
</Tip>

## 전형적인 워크플로

<Steps>
  <Step title="발견" icon="magnifying-glass">
    필터(또는 자연어 `query`)와 함께 **Expansion Search** 를 호출해 타깃 시장으로 확장하는 회사를 가져오세요. AI 의 "왜 일치하는지" 요약을 위해 `is_explain_match: true` 를 설정하세요.
  </Step>

  <Step title="회사 깊이 들여다보기" icon="building-magnifying-glass">
    결과에서 `domain_search_id` 를 가져와 **Company Expansion Detail** 을 호출해 한 시장 내 전체 정보 — 스테이지, 진출 현황, 이력, 시그널 — 를 읽으세요.
  </Step>

  <Step title="활동 피드 보기(선택)" icon="timeline">
    풍부하고 기간 범위가 지정된 이벤트 스트림을 위해, 관심 있는 시그널 유형과 날짜 범위와 함께 **Company Signal Events** 를 호출하세요.
  </Step>

  <Step title="비교 또는 지도 표시" icon="scale-balanced">
    대상 회사에서 시드된 나란히 비교하는 그리드에는 **Compare Company Expansions** 를, 이미 회사 집합이 있고 기성 지표를 원한다면 **Batch Company Expansion Summaries** 를, 순위가 매겨진 포인트를 지도에 표시하려면 **Expansion Rankings** 를 사용하세요.
  </Step>
</Steps>

## 공유 필터

발견용 엔드포인트(**Expansion Search**, **Expansion Overview**, **Expansion Rankings**)는 동일한 필터 어휘 — 확장 필터(스테이지, 궤적, 신선도, 스코프, 시그널 유형), 방향이 있는 지리 쌍(`froms` / `tos`) **및** 전체 회사 펌오그래픽 세트(산업, 기술, 직원 규모, 매출, 저장된 목록) — 를 받습니다. 필터는 [필터 개요](/ko/developer-guides/filters/overview) 에서 한 번 익히세요. 유효한 값은 [Expansion Reference](/ko/api-reference/endpoint/expansions/types) 와 [확장 신호의 작동 원리](/ko/knowledge-base/concepts/how-expansion-signals-work) 카탈로그에 있습니다.

<CardGroup cols={2}>
  <Card title="Expansion API 사용하기" icon="code" href="/ko/knowledge-base/concepts/expansion-api-quickstart">
    인증, 첫 호출, 페이지네이션, 그리고 점수 읽기.
  </Card>

  <Card title="실전 예제" icon="route" href="/ko/knowledge-base/concepts/expansion-signals-example">
    시장에서 시그널까지의 전체 워크스루.
  </Card>
</CardGroup>