> ## 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.

# 확장 필드 참조

> 확장 API의 필드별 사전—모든 요청 필터와 응답 필드, 그 유형, 허용 값, 의미.

<Info>
  이 페이지는 확장 API의 **필드 사전**입니다. 각 요청 필터가 무엇을 하는지, 각 응답 필드가 무엇을 의미하는지 설명합니다. 모델의 *이유*에 대해서는 [확장 신호의 작동 방식](/ko/knowledge-base/concepts/how-expansion-signals-work)을, 값 카탈로그는 [확장 신호의 작동 원리](/ko/knowledge-base/concepts/how-expansion-signals-work)를 참조하세요. 항상 최신 허용 값 목록을 보려면 [확장 분류 체계(Expansion Taxonomy)](/ko/api-reference/endpoint/expansions/types) 엔드포인트를 호출하세요.
</Info>

## 핵심 차원

모든 확장은 몇 개의 독립적인 축을 따라 기술됩니다. 이들을 혼동하지 마세요.

| 필드                | 무엇을 포착하는가                                | 값 예시                                                                   |
| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
| `stage`           | 기업이 한 시장에서 얼마나 진행했는가                     | `exploring`, `committing`, `expanding`, `scaling`, `established`       |
| `momentum`        | 지금 이 움직임의 **궤적**                         | `accelerating`, `advancing`, `steady`, `pulling_back`                  |
| flow(흐름)          | 시장 간 움직임의 **방향**. `froms` / `tos`로 표현합니다 | outbound(`froms`), inbound(`tos`), corridor(`froms`→`tos`)             |
| `freshness`       | 증거가 얼마나 **최근**인가                         | `fresh`, `cooling`, `stale`, `cold`                                    |
| `scope`           | 신규 시장인지, 기존 입지 내 성장인지                    | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | 확장이 얼마나 유의미한지를 나타내는 정렬 가능한 0–1 순위        | `0.72`                                                                 |

<Note>
  단계 slug는 `exploring`, `committing`, `expanding`, `scaling`, `established`이며, 각각 표시 이름 Exploring, Committing(투입 중), Expanding(확장 중), Scaling(규모 확대 중), Established에 대응합니다.
</Note>

<Warning>
  **흐름**(움직임의 방향)과 `momentum`(궤적)은 서로 다른 개념입니다. "전진 중인 기업"으로 필터링하는 것은 `momentum: ["advancing"]`이고, "*미국으로* 확장 중인 기업"으로 필터링하는 것은 `tos: ["US"]`입니다. 별도의 `direction` 요청 필드는 없습니다—흐름은 전적으로 `froms` / `tos`로 정해집니다.
</Warning>

## 요청 필터

### 시장(`froms` / `tos`)

지리는 방향이 있는 관계입니다: 기업은 **출발지**에서 **도착지**로 확장합니다. 두 개의 목록으로 모든 경우를 표현하며, 별도의 방향 플래그가 필요 없습니다.

| 파라미터            | 유형                      | 의미                                    |
| --------------- | ----------------------- | ------------------------------------- |
| `froms`         | string\[]\(ISO alpha-2) | **출발** 시장—기업이 어디에서부터 확장하는지(본거지 / 본사). |
| `tos`           | string\[]\(ISO alpha-2) | **도착** 시장—기업이 어디로 확장하는지.              |
| `exclude_froms` | string\[]\(ISO alpha-2) | 제외할 출발 시장.                            |
| `exclude_tos`   | string\[]\(ISO alpha-2) | 제외할 도착 시장.                            |

| 보내는 값                          | 얻는 결과                         |
| ------------------------------ | ----------------------------- |
| `tos: ["US"]`                  | 미국으로 **진입하는** 모든 기업(inbound). |
| `froms: ["CN"]`                | 중국 기업이 **어디로든** 확장(outbound). |
| `froms: ["CN"]`, `tos: ["US"]` | **CN → US 코리도**만.             |
| 둘 다 없음                         | 전 세계 모든 확장.                   |

### 확장 신호 필터

| 파라미터               | 유형        | 의미                                                               |
| ------------------ | --------- | ---------------------------------------------------------------- |
| `stages`           | string\[] | 하나 이상의 확장 단계로 필터링합니다.                                            |
| `momentum`         | string\[] | 궤적으로 필터링합니다(`accelerating`/`advancing`/`steady`/`pulling_back`). |
| `freshness`        | string\[] | 증거의 최근성으로 필터링합니다(`fresh`/`cooling`/`stale`/`cold`).              |
| `scopes`           | string\[] | `entering_new_market` / `expanding_within_presence`로 필터링합니다.     |
| `signal_types`     | string\[] | 특정 신호 유형으로 제한합니다(`HIRE`, `OFFICE`, `AD`, `NEWS`, …).             |
| `signal_strengths` | string\[] | 증거 강도 버킷으로 필터링합니다(예: `high`, `very_high`).                       |
| `min_signal_count` | integer   | 확장 신호의 최소 개수—발자취가 큰 움직임을 드러냅니다.                                  |
| `ahead_of_pace`    | boolean   | 해당 시장의 통상 속도보다 빠르게 움직이는 기업만.                                     |
| `only_contraction` | boolean   | 위험 상태 / 축소 중인 시장만.                                               |
| `min_markets`      | integer   | 기업이 해당 기간 내에 진입한 서로 다른 신규 시장의 최소 개수.                             |

### 기업 정보

| 파라미터                        | 유형           | 의미                                                                                             |
| --------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
| `verticals`, `technologies` | string\[]    | 기업 업종 / 기술 스택 필터.                                                                              |
| `employees`                 | number\[]\[] | 임직원 규모 범위, 예: `[[50, 200]]`.                                                                   |
| `founded_dates`             | number\[]    | 설립 연도 범위 `[from, to]`.                                                                         |
| `revenues`                  | number\[]    | 매출 범위(USD) `[from, to]`.                                                                       |
| `keywords`                  | string\[]    | 자유 텍스트 테마 범위 지정.                                                                               |
| `companies`                 | string\[]    | `domain_search_id`, 도메인 또는 LinkedIn URL의 임의 조합으로 특정 기업으로 범위를 지정합니다(도메인 / URL은 가장 상위 기업으로 해석됨). |

### 기간 창 및 검색

| 파라미터                 | 유형        | 의미                                                                                                                                                 |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transitioned_dates` | string\[] | 신호 / 전환 창을 ISO `[from, to]` 범위로 지정.                                                                                                                |
| `window_days`        | integer   | 일 단위 롤링 창. `transitioned_dates`가 제공되지 않을 때 사용.                                                                                                     |
| `query`              | string    | 자연어 검색—Pubrio가 이를 필터로 해석합니다(`filters`에 반영되어 반환됨).                                                                                                  |
| `is_explain_match`   | boolean   | 각 기업에 실제 신호에 근거한 AI `match_summary`를 추가합니다. 인용되는 신호 수와 배치 크기는 모두 `per_page`에 따라 달라집니다. 채용 공고, 광고 캠페인처럼 발생 빈도가 높은 소스는 개별적으로 나열하지 않고 건수로 요약되어 표시됩니다. |
| `sort_by`            | string    | 결과 정렬 방식: `expansion_score`, `signal_count`, 또는 `company_ranking`. 생략하면 기본값(가장 최근에 전환된 순)이 적용됩니다.                                                  |

## 응답 필드

### 기업별 / 시장별 `stage`

| 필드                                                                  | 의미                                                                                                                                             |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage.slug`                                                        | 현재 단계(`exploring` … `scaling`).                                                                                                                |
| `stage.expansion_score`                                             | 정렬 가능한 0–1 유의미도 순위.                                                                                                                            |
| `stage.scope`                                                       | 신규 시장 vs 기존 입지 내.                                                                                                                              |
| `stage.direction`                                                   | 해당 단계의 궤적: `advancing`, `steady`, `retreating`, 또는 `new`. 이는 **궤적** 축의 응답 측 표현으로, `momentum` 요청 파라미터로 필터링하는 것과 같은 축입니다—값 집합이 다르므로 그에 맞게 매핑하세요. |
| `stage.freshness`                                                   | 최신 증거의 최근성 버킷.                                                                                                                                 |
| `stage.signal_count`                                                | 이 시장에서 활성 상태인 확장 신호의 수.                                                                                                                        |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | 주요 타임스탬프.                                                                                                                                      |

### 신호, 입지 및 설명

| 필드                | 의미                                                                                                                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signals[]`       | 기반이 되는 증거: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`.                                                       |
| `presence[]`      | 알려진 시장 내 발자취(사무소 / 법인): `presence_type`, `presence_strength`, `address`, `known_since`.                                                                                                        |
| `timeline[]`      | 단계 전환 이력: `stage_slug`, `transitioned_at`, `transition_kind`.                                                                                                                                  |
| `other_markets[]` | 해당 기업의 다른 활성 시장. 각각에 단계 + 카운트가 함께 제공됩니다.                                                                                                                                                       |
| `match_summary`   | *(`is_explain_match: true`일 때)* `{ text, citations }`—AI가 제시하는 "왜 일치하는가"로, 해당 기업의 실제 신호를 인용합니다. 각 인용에는 `count` 필드가 있습니다. 실제 개별 신호인 경우 `null`이며, 채용 공고나 광고 캠페인처럼 기간 내 건수 집계를 나타내는 인용인 경우 정수입니다. |

<Note>
  `expansion_score`는 **정렬 가능한 순위**입니다(기업 간 비교 가능). 이는 내부 모델 신뢰도와는 별개이며, 공개 API는 그 신뢰도를 반환하지 않습니다.
</Note>