확장 API 사용하기

이 빠른 시작 가이드는 몇 번의 호출만으로 실제 확장 신호를 읽는 단계까지 안내합니다. 이미 Pubrio API 키가 있다고 가정합니다—생성하려면 인증을 참고하세요.

사전 준비

Pubrio API 키(인증 참고).
회사의 domain_search_id. 회사 검색 엔드포인트에서 얻을 수 있습니다.

모든 확장 엔드포인트는 POST이며 JSON 본문을 받습니다. 인증에 설명된 대로 모든 요청에 자격 증명을 포함하세요.

1단계 — 회사의 확장 조회하기

단일 회사로 시작하여, 그 회사가 확장하고 있는 모든 시장을 나열합니다.

POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}

2단계 — 결과 읽기

markets_summary의 각 항목은 해당 기업이 활동 중인 하나의 시장을 설명합니다:

stage_slug — 그 시장에서 기업이 얼마나 진행했는지(exploring → scaling).
signal_count / distinct_type_count — 그 시장을 뒷받침하는 증거량과, 몇 가지 신호 유형에 걸쳐 있는지.
latest_signal_at — 가장 최근 신호의 최신성.
signal_velocity_30d / signal_velocity_90d — 활동이 가속되는 속도.
rank_now — 이 기업 기준 해당 시장의 현재 순위(1 = 가장 강함).
is_home_market — 그 기업의 본사 소재 국가인지 여부.

가장 신선한 이동 기업을 찾거나 궤적으로 필터링하려면, 다음에 소개하는 발견용 엔드포인트(freshness, momentum)를 사용하세요.

3단계 — 시장 전체 탐색하기

회사 중심이 아닌 시장 중심으로 작업하려면 확장 시장 상세를 사용하세요. 표준 page / per_page 매개변수로 페이지네이션됩니다. 지리는 방향이 있는 from → to 관계로, 두 개의 목록으로 표현합니다: froms(출발 / 본사 시장)와 tos(도착 시장). 질문에 맞는 패턴을 선택하세요:

POST /expansions/search
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "tos": ["GB"],
  "page": 1,
  "per_page": 25
}

metadata.pagination을 읽어 결과를 페이지 단위로 넘기세요.

{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}

page를 증가시켜 다음 페이지를 요청하세요. per_page는 플랜에 따라 상한이 정해지며, 상한을 초과하는 값을 명시적으로 요청하면 조용히 잘리는 대신 오류가 반환됩니다. 알아두면 좋은 두 가지 기본값:

정렬 — 결과는 관련성 순서(여러 신호 유형으로 상호 검증된 회사가 먼저, 그다음 최신순)로 반환됩니다. 순수 최신순은 sort_by: "recent"를, 또는 expansion_score / signal_count / company_ranking을 전달하세요.
간결한 응답 — API 키 응답은 기본적으로 시장 롤업(metadata.aggregate, top origins/destinations, timeline)과 모델 세부 정보를 생략합니다. 필요하면 is_include_metadata: true를 전달하세요.

4단계 — 증거로 드릴다운하기

회사의 움직임 뒤에 있는 개별 신호를 원할 때는 회사 신호 이벤트를 호출하세요.

POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}

이 엔드포인트는 total_entries와 total_pages를 반환합니다—1페이지부터 total_pages페이지까지 요청하세요(즉, page < total_pages인 동안 계속).

필터링 참조

대부분의 확장 엔드포인트는 다음 필터를 받습니다. 유효한 값은 확장 신호의 작동 원리에 나열되어 있습니다.

필터	목적
`stages`	하나 이상의 확장 단계로 제한.
`freshness`	증거의 최신성으로 제한.
`momentum`	궤적(`accelerating`/`advancing`/`steady`/`pulling_back`)으로 제한.
`scopes`	시장 진입 범위로 제한.
`signal_types`	특정 신호 유형으로 제한.
`froms`	출발 / 본사 시장(여기서 확장).
`tos`	타깃 시장(여기로 확장).
`companies`	`domain_search_id`, 도메인 또는 LinkedIn URL로 특정 기업으로 범위 지정.

companies 필터는 식별자 유형의 임의 조합을 받습니다—먼저 ID로 해석할 필요가 없습니다:

POST /expansions/search
{ "companies": ["stripe.com", "airbnb.com"] }

POST /expansions/search
{ "companies": ["https://www.linkedin.com/company/stripe"] }

POST /expansions/search
{ "companies": ["550e8400-e29b-41d4-a716-446655440002"] }

흐름과 궤적을 혼동하지 마세요. 흐름(시장 간 움직임의 방향)은 froms / tos로 설정합니다—direction 요청 필터는 없습니다. 궤적(움직임이 어떻게 진행되는지)은 momentum 필터이며, 응답에서는 direction 필드로 나타납니다.

지식베이스

가이드

개념

사례 연구

사전 준비

1단계 — 회사의 확장 조회하기

2단계 — 결과 읽기

3단계 — 시장 전체 탐색하기

4단계 — 증거로 드릴다운하기

필터링 참조

다음 단계

실전 예제

확장 엔드포인트

​사전 준비

​1단계 — 회사의 확장 조회하기

​2단계 — 결과 읽기

​3단계 — 시장 전체 탐색하기

​4단계 — 증거로 드릴다운하기

​필터링 참조

​다음 단계

실전 예제

확장 엔드포인트

사전 준비

1단계 — 회사의 확장 조회하기

2단계 — 결과 읽기

3단계 — 시장 전체 탐색하기

4단계 — 증거로 드릴다운하기

필터링 참조

다음 단계