국가별 가계 지출
1 크레딧/v1/economy/consumer-spendEurostat의 국가별, 지출 분류별 연간 가계 지출을 반환합니다. 단위는 백만 유로, 1인당 유로, 전체 대비 비중 중에서 고릅니다. 아직 발표되지 않은 연도는 0이 아니라 null입니다.
country_code, category, from_year, to_year, unit
Economy API
경제 데이터 API
SocialCrawl API 키로 가계·여행 지출, 미국 연방 정부 지출과 계약, 미국 수입업체의 공급처를 구조화 JSON으로 가져옵니다. 출처는 Eurostat와 USAspending.gov입니다. 호출은 크레딧으로 과금됩니다.
/v1/economy
활성 엔드포인트는 5개입니다. 소비·여행 지출, 연방 지출과 계약, 수입업체입니다.
- GET /v1/economy/consumer-spend
- GET /v1/economy/tourism-spend
- GET /v1/economy/government-spend
- GET /v1/economy/government-contracts
- GET /v1/economy/imports
경제 엔드포인트
공식 지출 통계와 공개 무역 기록을 읽는 엔드포인트입니다. 국가별 유럽 가계·여행 지출, 지역별 미국 연방 정부 지출, 계약 건별 내역, 미국 수입업체의 해외 공급처를 제공합니다. 데이터 API만 지원합니다.
국가별 여행 지출
1 크레딧/v1/economy/tourism-spend국가 거주자의 여행 지출을 교통, 숙박, 식당 등 분류별로 반환합니다. 출장과 개인 목적, 국내와 해외 목적지, 총액과 여행당·1박당 기준으로 필터링할 수 있습니다.
country_code, category, purpose, destination, measure, from_year, to_year
지역별 미국 연방 지출
1 크레딧/v1/economy/government-spendUSAspending.gov 기준으로 산업 코드, 품목 코드, 키워드에 해당하는 연방 지출을 주, 카운티, 국가별로 반환합니다. 금액 순으로 정렬되며 기간 합계가 함께 옵니다.
naics, psc, keyword, from_date, to_date, geo, scope, award_type
미국 연방 계약 건별 내역
페이지당 1 크레딧/v1/economy/government-contracts수혜 기업, 금액, 발주 기관, NAICS, 설명, 기간, 수행 장소가 담긴 계약 건을 반환합니다. recipient, keyword, naics, psc 중 하나가 필요합니다. 결과가 없으면 빈 목록이며 환불됩니다.
recipient, keyword, naics, psc (one required), from_date, to_date, type, sort, order, limit, page
미국 수입업체 공급처
20 크레딧/v1/economy/imports미국 수입업체의 세관 기록을 반환합니다. 선적 건수 기준 해외 공급처 상위 목록, 취급하는 HS 품목, 최근 선하증권이 포함됩니다. 브랜드 이름은 신고 업체로 연결되며 Nike는 Nike Usa를 반환합니다.
company, limit
Economy API5개 엔드포인트 지원
문서 보기국가와 지출 항목별 연간 가계 소비 지출을 유로 백만 단위, 1인당 금액, 전체 대비 비중 중에서 골라 돌려줍니다.
국가별로 특정 품목에 쓰는 돈을 비교하거나 한 나라의 소비 구성이 해마다 어떻게 달라지는지 볼 때 사용합니다.
1크레딧
GET/v1/economy/consumer-spend?country_code=DE%2CFR&category=transport%2Cfood&from_year=2020&to_year=2024&unit=eur_millions
country_code · One or more ISO 3166-1 alpha-2 country codes, comma-separated (up to 10), e.g. `DE,FR,GR`. `EU27` returns the European Union total.
$ curl https://www.socialcrawl.dev/v1/economy/consumer-spend?country_code=DE%2CFR&category=transport%2Cfood&from_year=2020&to_year=2024&unit=eur_millions \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다경제 API 동작
경제 데이터도 다른 SocialCrawl 엔드포인트와 같습니다. API 키로 GET /v1/economy/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다. 공식 출처별 키와 별도 SDK는 필요 없습니다.
호출 인증
x-api-key 헤더에 키를 보냅니다. 소셜, 검색, 커머스 엔드포인트와 같은 키를 사용합니다.
GET과 쿼리 파라미터
라우트는 모두 GET입니다. consumer-spend와 tourism-spend에는 country_code가, imports에는 company가 필요하고 government-contracts에는 recipient, keyword, naics, psc 중 하나가 필요합니다. 과금 전에 검증합니다.
크레딧 과금
지출과 계약 호출은 1 크레딧입니다. 수입업체 조회는 limit과 관계없이 20 크레딧입니다. 캐시 히트는 0 크레딧입니다.
JSON 봉투
응답의 바깥 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. data 안의 구조는 엔드포인트마다 다릅니다.
연동 순서
산업 코드에서 시작해 그 뒤의 계약 건을 찾고, 이어서 기업의 수입 내역을 조회합니다. Eurostat 엔드포인트 두 개는 국가별 시장 규모 산정에 단독으로 사용합니다.
01연방 지출
GET /v1/economy/government-spend?naics=…산업 코드별 금액 순 지역 목록입니다.
개별 계약을 받기 전에 연방 예산이 어디로 가는지 확인합니다.
02계약 건별 내역
GET /v1/economy/government-contracts?naics=…수혜 기업, 금액, 발주 기관이 담긴 계약 목록입니다.
지출 합계 뒤에 있는 기업과 기관을 확인합니다.
03수입업체 조회
GET /v1/economy/imports?company=…해외 공급처 상위 목록, HS 품목, 선하증권입니다.
기업이 누구에게서 무엇을 수입하는지 확인합니다.
요청
GET /v1/economy/consumer-spend
?country_code=DE,FR
&category=transport
&unit=eur_millions
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/economy/imports?company=Nike응답 봉투
{
"success": true,
"data": {
"series": [
{
"country_code": "DE",
"category": "transport",
"points": [{ "year": 2022, "value": 253929 }]
}
],
"unit": "eur_millions",
"source_note": "…"
},
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}data 형태
엔드포인트마다 고유한 구조화 객체를 반환합니다. 시계열, 금액 순 지역 목록, 계약 목록, 공급처 요약 모두 원래 출처의 파서 없이 읽을 수 있는 JSON입니다.
시계열 (consumer-spend)consumer-spend
국가·분류별 series[]와 연도·값 points[], dataset, unit, source_note
시계열 (tourism-spend)tourism-spend
국가·분류별 유로 단위 series[]와 적용된 purpose, destination, measure
지역 목록 (government-spend)government-spend
code, name, amount, population, per_capita가 있는 regions[]와 total_amount, geo_layer, filters
계약 목록 (government-contracts)government-contracts
award_id, type, recipient_name, amount, awarding_agency, naics, description, 기간, place_of_performance가 있는 items[]
수입업체 기록 (imports)imports
company, top_suppliers, hs_codes, recent_shipments, matches, selection
게이트웨이
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. 경제 데이터 전용 사이드카가 아닙니다.
- 01
엣지 수신
Next.js catch-all이 Hono 소셜 API로 들어갑니다. request_id를 발급하고 키를 인증한 뒤 분당 600회 한도와 키당 동시 50건을 적용합니다.
- 02
검증 후 차감
레지스트리에서 economy 라우트를 찾습니다. 필수 파라미터 검증이 먼저입니다. 잘못된 입력은 400이며 과금하지 않습니다. 유효 호출은 업스트림 전에 티어 비용을 원자적으로 차감합니다.
- 03
캐시 또는 조회
platform, resource, params로 캐시 키를 만듭니다. 히트면 즉시 반환하고 credits_used는 0입니다. 미스면 출처를 직접 조회합니다. 지출과 수입업체 응답은 원본 데이터가 하루 단위로 갱신되므로 수 시간 캐시됩니다.
- 04
정규화 후 반환
출처 응답을 엔드포인트별 객체로 재구성하고 검증한 뒤 성공 봉투로 감싸 빌링 감사에 남깁니다.
과금 규칙
- 지출과 계약 호출은 1 크레딧입니다.
- 계약 검색은 페이지당 1 크레딧입니다.
- 수입업체 조회는 limit과 관계없이 20 크레딧입니다.
- 캐시 히트는 0 크레딧입니다.
- 결과가 없으면 404 또는 빈 목록이며 환불됩니다.
- 잘못된 파라미터는 400이며 과금하지 않습니다.
- 잔액이 없으면 402이며 과금하지 않습니다.
- 미국 수입 기록이 없는 회사 이름은 404이며 0 크레딧입니다.
- 차감 후 출처 장애는 환불 경로가 적용됩니다.
데이터 수집
경제 데이터는 공식 통계와 공개 기록을 읽어 하나의 JSON 형태로 반환합니다. 출처마다 질의 방식을 따로 익힐 필요가 없습니다.
API에서의 경제 데이터
국가, 산업, 기업에 대한 지출과 무역 정보를 제공합니다. 읽기 전용 참조 데이터이며 시세나 소셜 콘텐츠가 아닙니다.
숫자의 출처
가계·여행 지출은 유럽연합 통계청 Eurostat에서 가져옵니다. 연방 지출과 계약은 미국 정부 공식 출처인 USAspending.gov에서 가져옵니다. 수입업체 기록은 미국 세관에 공개된 선하증권 신고 자료입니다.
응답 형태
success, data, credits_used, request_id, cached를 담은 통합 JSON 봉투를 반환합니다. 값이 없으면 0이 아니라 null이며 응답에 출처 메모가 포함됩니다.
미제공 항목
Eurostat 지출은 EU와 EEA 국가 및 일부 후보국을 다룹니다. 수입업체 데이터는 미국 해상 화물 수입만 다루며 항공 화물, 수출, 미국 외 무역은 없습니다. 일부 수입업체는 선하증권을 비공개로 돌려 둡니다.
필드 매핑
Eurostat annual dataset→ series[] with year and value pointsEurostat 연간 값은 국가·분류별 시계열 포인트가 됩니다.
USAspending.gov award totals→ regions[] ranked by amountUSAspending.gov 합계는 금액 순 지역 목록이 됩니다.
federal award record→ items[] contract rows연방 계약 건은 계약 행 하나가 됩니다.
customs bill-of-lading records→ importer supplier dossier세관 선하증권은 공급처, HS 품목, 선적 목록으로 집계됩니다.
이 API의 활용 분야
이 API가 가장 많이 사용되는 작업입니다.
5active Economy endpoints in the registry
1 / 20지출·계약 1 크레딧, 수입업체 조회 20 크레딧 사다리
시장 규모 산정과 기업 소싱 조사
호출은 government-spend와 government-contracts를 함께 써서 지출 대상을 찾고, imports로 판매자의 공급처를 확인하는 흐름에 집중됩니다. Eurostat 엔드포인트는 국가 비교에 사용됩니다. 질문 하나에 GET 하나로 답하며 없는 연도는 0이 아니라 null입니다. 지출과 계약 호출은 1 크레딧, 수입업체 조회는 20 크레딧입니다. 카탈로그 전체에 같은 SocialCrawl 키를 사용합니다.
지출과 계약 호출은 보통 수 초 안에 반환됩니다. 수입업체 조회는 8초에서 12초가 걸리고 최대 25초 안팎까지 걸릴 수 있으므로 클라이언트 타임아웃을 45초 이상으로 설정해야 합니다.
활용 사례
이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.
시장 규모 분석
Python, pandas, 노트북consumer-spend와 tourism-spend로 국가·분류별 수요 규모를 산정합니다. 1인당 또는 비중 단위로 규모가 다른 국가를 비교합니다.
공공 부문 영업
Node, CRM 연동, crongovernment-spend로 연방 예산이 들어가는 주와 산업을 찾은 뒤 government-contracts로 그 뒤의 계약과 수혜 기업을 나열합니다.
소싱과 경쟁사 조사
Go, 큐, 스프레드시트공급처 또는 경쟁사 검토에 앞서 imports로 브랜드의 해외 공급처 상위 목록, HS 품목, 최근 선적을 확인합니다.
호출 예시
지출과 계약 호출은 1 크레딧입니다. 수입업체 조회는 20 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/economy/consumer-spend?country_code=DE,FR&category=transport&unit=eur_millions" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/economy/government-spend?naics=4811&geo=state" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/economy/imports?company=Nike&limit=10" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
Economy API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
비교
SocialCrawl과 출처 API를 직접 호출, 뭐가 다른가요?
같은 Economy 데이터를 받는 두 가지 방법을 나란히 비교했어요. 인증부터 비용까지 한눈에 확인해 보세요.
| 항목 | SocialCrawl | 출처 API를 직접 호출 |
|---|---|---|
| 요청 형태 | 모든 엔드포인트가 쿼리 파라미터만 쓰는 GET이에요 | Eurostat는 데이터셋 코드와 JSON-stat 파싱이, USAspending.gov는 JSON POST 본문이 필요해요 |
| 응답 형태 | 연도·값 시계열, 금액순 지역 목록, 계약 목록, 공급처 요약으로 와요 | 다차원 JSON-stat 큐브와 중첩된 필터 응답을 직접 평탄화해야 해요 |
| 결측값 | 발표되지 않은 해는 0이 아니라 null로 와요 | 결측은 상태 플래그에 들어 있어서 직접 읽어야 해요 |
| 수입업체 공급처 | 브랜드 이름을 넣으면 해외 공급처 상위 목록과 최근 선하증권이 와요 | 회사 이름으로 찾는 무료 공식 조회는 없어요 |
| 요금 | 지출 호출은 1크레딧, 수입업체 조회는 20크레딧이고 100 크레딧을 무료로 받아요 | 공식 API는 무료지만 연동 개발과 운영은 직접 해야 해요 |
요청 형태
SocialCrawl
모든 엔드포인트가 쿼리 파라미터만 쓰는 GET이에요
출처 API를 직접 호출
Eurostat는 데이터셋 코드와 JSON-stat 파싱이, USAspending.gov는 JSON POST 본문이 필요해요
응답 형태
SocialCrawl
연도·값 시계열, 금액순 지역 목록, 계약 목록, 공급처 요약으로 와요
출처 API를 직접 호출
다차원 JSON-stat 큐브와 중첩된 필터 응답을 직접 평탄화해야 해요
결측값
SocialCrawl
발표되지 않은 해는 0이 아니라 null로 와요
출처 API를 직접 호출
결측은 상태 플래그에 들어 있어서 직접 읽어야 해요
수입업체 공급처
SocialCrawl
브랜드 이름을 넣으면 해외 공급처 상위 목록과 최근 선하증권이 와요
출처 API를 직접 호출
회사 이름으로 찾는 무료 공식 조회는 없어요
요금
SocialCrawl
지출 호출은 1크레딧, 수입업체 조회는 20크레딧이고 100 크레딧을 무료로 받아요
출처 API를 직접 호출
공식 API는 무료지만 연동 개발과 운영은 직접 해야 해요
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기SocialCrawl 경제 API는 무엇인가요?
소셜 엔드포인트와 같은 키로 공식 경제 데이터를 JSON으로 받는 엔드포인트 5개예요. 국가별 가계·여행 지출, 미국 연방 정부 지출과 계약, 미국 수입업체의 해외 공급처를 다뤄요. 앞의 네 가지는 Eurostat와 USAspending.gov 데이터이고, 수입업체 조회는 미국 세관 선하증권 기록을 바탕으로 해요.
Eurostat 소비 지출 데이터를 API로 받을 수 있나요?
네. GET /v1/economy/consumer-spend에 국가 코드를 하나 이상 넣으면 식비, 주거, 교통 같은 COICOP 분류별 연간 가계 지출이 연도·값 시계열로 와요. 단위는 백만 유로, 1인당 유로, 전체 대비 비중 중에서 고를 수 있어요. Eurostat가 아직 발표하지 않은 해는 0이 아니라 null이에요.
미국 연방 정부 예산이 어느 산업으로 가는지 어떻게 확인하나요?
GET /v1/economy/government-spend에 NAICS 코드를 넣어 호출해 보세요. 예를 들어 naics=4811은 정기 항공 운송이에요. 주, 카운티, 국가별 지출이 금액이 큰 순서로 오고 기간 합계도 함께 와요. psc, keyword, 기간, award_type으로 좁힐 수 있고 기본값은 직전 미국 연방 회계연도예요.
미국 연방 정부 계약 건별 내역도 검색할 수 있나요?
네. GET /v1/economy/government-contracts에 recipient, keyword, naics, psc 중 하나를 넣으면 수혜 기업, 금액, 발주 기관, NAICS, 설명, 기간, 수행 장소가 담긴 계약 목록이 와요. page나 cursor로 다음 페이지를 이어서 받을 수 있어요. 결과가 없으면 빈 목록이 오고 과금되지 않아요.
미국 기업이 어디서 수입하는지 알 수 있나요?
네. GET /v1/economy/imports에 회사 이름을 넣으면 해외 공급처 상위 목록과 선적 건수, 취급하는 HS 품목, 최근 선하증권이 와요. Nike를 넣으면 신고 업체 Nike Usa로 연결되고, selection 필드에 어떤 기준으로 골랐는지 담겨요. 미국으로 들어오는 해상 화물만 다뤄요.
경제 API는 요금이 얼마인가요?
지출·계약 엔드포인트는 호출당 1 credit이고, 수입업체 조회는 limit과 상관없이 20 크레딧이에요. 신규 계정은 카드 없이 100 크레딧을 무료로 받아요. 결과가 없으면 404나 빈 목록으로 오고 환불돼요. 캐시 기간 안에 같은 요청을 반복하면 0크레딧이에요.
경제 데이터는 얼마나 최신인가요?
각 출처가 발표하는 일정을 그대로 따라요. Eurostat는 연 단위이고 최근 연도는 잠정치인 경우가 많아요. USAspending.gov는 각 기관이 보고한 계약이 반영되고, 세관 선하증권은 며칠 늦게 매일 올라와요. 응답은 최대 하루 캐시되고, 응답에 데이터셋과 출처 메모가 함께 와서 어떤 데이터인지 바로 확인할 수 있어요.
Economy 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Economy 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Economy 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
Economy 스크래핑 API와 공식 Economy API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Economy 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.
AI에게 SocialCrawl을 물어보세요