NEWS

APIZOA의 새로운 소식을 만나보세요

서비스 공지부터 API 활용 이야기와 업데이트까지 한곳에서 전해드립니다.

블로그

Data USA API 활용법

Data USA API로 미국의 인구, 산업, 직업과 교육 데이터를 조회하고 활용하는 방법을 알아봅니다.

Data USA란?

Data USA는 미국의 공공 데이터를 탐색하고 비교할 수 있도록 제공하는 데이터 플랫폼입니다. 웹사이트의 시각화에 사용되는 데이터를 API로도 공개하고 있어 미국의 지역, 인구, 산업, 직업과 교육 정보를 애플리케이션이나 분석 프로젝트에서 활용할 수 있습니다.

Data USA의 API는 데이터를 cube라는 단위로 구성합니다. cube는 하나의 데이터셋과 비슷하며, 조회할 분류 항목인 drilldown, 계산하거나 집계할 값인 measure, 결과 범위를 제한하는 filter를 조합해 요청합니다.

공식 API 문서는 Data USA API 소개에서 확인할 수 있습니다.

얻을 수 있는 데이터

Data USA는 미국 정부기관과 공공 데이터셋을 결합해 다양한 주제의 데이터를 제공합니다.

  • 인구와 지역: 주, 카운티, 도시와 의회 선거구별 인구 및 인구통계
  • 산업: 산업별 사업체 수, 고용, 임금, 생산과 투입·산출 정보
  • 직업: 직업별 고용 인원, 임금, 예상 성장률과 필요한 기술
  • 교육: 대학별 입학, 등록, 졸업률, 학위 과정, 학비와 재정 지원
  • 건강: 주와 카운티 수준의 건강 지표 및 의료 관련 통계
  • 주택과 복지: 주거, 노숙과 지역사회 관련 공개 지표
  • 교통과 물류: 지역 간 화물 이동, 품목, 운송 방식, 가치와 중량
  • 정부 지출: 미국 연방정부의 분야별 지출 정보
  • 선거: 대통령, 상원과 하원 선거 결과에 관한 데이터

지역 분류에는 주, 카운티, 도시, 대도시권과 PUMA 등이 포함됩니다. 산업, 직업, 학위, 대학과 제품·서비스 분류도 제공하므로 시장 조사나 지역 비교, 교육 및 노동시장 분석에 활용할 수 있습니다.

주요 데이터 출처

Data USA는 자체 조사만으로 데이터를 만드는 서비스가 아니라 여러 공식 출처의 데이터를 정리해 제공합니다. 주요 출처는 다음과 같습니다.

  • 미국 인구조사국의 ACS와 PUMS, County Business Patterns
  • 노동통계국의 고용, 임금, 물가와 직업 전망
  • 경제분석국의 산업 투입·산출 데이터
  • 교육부와 IPEDS의 대학 및 고등교육 데이터
  • 교통부의 Freight Analysis Framework
  • USAspending.gov의 연방정부 지출 데이터
  • O*NET의 직업별 기술 데이터

데이터셋마다 조사 방식과 갱신 주기, 제공 가능한 지역 단위가 다릅니다. 분석 전에 Data Sources에서 출처와 주의사항을 확인하는 것이 좋습니다.

API 구조 이해하기

기본 API 주소는 다음과 같습니다.

CODE
https://api.datausa.io/tesseract

주로 사용하는 엔드포인트는 네 가지입니다.

CODE
GET /cubes
GET /cubes/{name}
GET /members?cube={name}&level={level}
GET /data.{format}

/cubes로 데이터셋을 찾고, /cubes/{name}으로 사용할 수 있는 차원과 측정값을 확인합니다. /members는 주나 연도처럼 필터에 넣을 실제 값을 찾을 때 사용하며, /data.{format}에서 원하는 데이터를 조회합니다.

1 데이터셋 찾기

먼저 사용 가능한 모든 cube를 조회합니다.

CODE
curl "https://api.datausa.io/tesseract/cubes"

응답의 cubes 배열에는 cube 이름과 주제, 데이터 출처, 데이터셋 설명이 포함됩니다. 인구 데이터를 조회하려면 예제에서 사용하는 acs_yg_total_population_5 같은 cube를 선택할 수 있습니다.

목록이 많으므로 애플리케이션에서는 cube 이름, 주제와 출처를 별도로 저장하거나 검색할 수 있는 관리 화면을 만드는 것이 편리합니다.

2 스키마 확인하기

선택한 cube에서 사용할 수 있는 필드를 확인합니다.

CODE
curl "https://api.datausa.io/tesseract/cubes/acs_yg_total_population_5"

스키마에는 다음 정보가 포함됩니다.

  • dimensions: 지역, 연도처럼 데이터를 나누는 기준
  • levels: State, County처럼 차원의 구체적인 분류 단계
  • measures: Population처럼 집계하거나 비교할 수 있는 수치
  • annotations: 출처, 주제와 데이터셋에 관한 설명

요청에 사용할 이름은 화면에 보이는 문구와 다를 수 있으므로 반드시 스키마에 표시된 정확한 이름을 사용해야 합니다.

3 분류값 확인하기

State 수준에서 사용할 수 있는 모든 값을 조회하는 예제입니다.

CODE
curl "https://api.datausa.io/tesseract/members?cube=acs_yg_total_population_5&level=State"

이 결과로 주 이름과 식별자를 확인할 수 있습니다. 필터 UI의 선택 항목을 구성하거나 지원되는 지역 범위를 파악할 때 유용합니다.

Alabama처럼 특정 주를 필터링할 때는 표시 이름보다 04000US01 같은 member key를 사용하는 경우가 있으므로 응답의 식별자를 함께 저장해야 합니다.

4 실제 데이터 요청

2023년 미국 주별 인구를 조회하는 공식 문서의 예제 구조입니다.

CODE
https://api.datausa.io/tesseract/data.jsonrecords
  ?cube=acs_yg_total_population_5
  &drilldowns=State,Year
  &measures=Population
  &include=Year:2023
  &limit=100,0

한 줄로 요청하면 다음과 같습니다.

CODE
curl "https://api.datausa.io/tesseract/data.jsonrecords?cube=acs_yg_total_population_5&drilldowns=State,Year&measures=Population&include=Year:2023&limit=100,0"

각 파라미터의 역할은 다음과 같습니다.

  • cube: 조회할 데이터셋
  • drilldowns: 결과를 나누어 볼 차원
  • measures: 조회하거나 집계할 수치
  • include: 특정 연도나 지역만 포함하는 필터
  • limit: 조회 건수와 시작 위치

limit=100,0에서 첫 번째 숫자는 최대 결과 수, 두 번째 숫자는 offset입니다. 다음 페이지를 조회하려면 offset을 늘립니다.

응답 구조 읽기

data.jsonrecords 응답은 읽기 쉬운 객체 배열을 포함한 JSON입니다.

CODE
{
  "annotations": {
    "dataset_name": "ACS 5-year Estimate",
    "source_name": "Census Bureau"
  },
  "page": {
    "limit": 100,
    "offset": 0,
    "total": 52
  },
  "columns": ["State ID", "State", "Year", "Population"],
  "data": [
    {
      "State ID": "04000US01",
      "State": "Alabama",
      "Year": 2023,
      "Population": 5054253
    }
  ]
}
  • annotations에는 데이터 출처와 주제, 데이터셋 설명이 들어 있습니다.
  • page에는 limit, offset과 전체 결과 수가 들어 있습니다.
  • columns에는 반환된 열 이름이 표시됩니다.
  • data에는 실제 조회 결과가 객체 배열로 제공됩니다.

요청하지 않은 ID 열도 응답에 포함될 수 있습니다. 화면에 표시할 필드만 별도로 변환하되 원본 식별자는 데이터 연결을 위해 보관하는 것이 좋습니다.

자바스크립트 예제

브라우저나 Next.js 서버 코드에서는 URLSearchParams를 사용하면 쿼리를 안전하게 구성할 수 있습니다.

CODE
const params = new URLSearchParams({
  cube: "acs_yg_total_population_5",
  drilldowns: "State,Year",
  measures: "Population",
  include: "Year:2023",
  limit: "100,0",
});

const url =
  `https://api.datausa.io/tesseract/data.jsonrecords?${params}`;
const response = await fetch(url);

if (!response.ok) {
  throw new Error(`Data USA 요청 실패: ${response.status}`);
}

const result = await response.json();

const states = result.data.map((row) => ({
  id: row["State ID"],
  name: row.State,
  year: row.Year,
  population: row.Population,
}));

외부 API를 화면에서 매번 직접 호출하기보다 서버에서 조회하고 적절한 시간 동안 캐시하면 응답 속도와 안정성을 개선할 수 있습니다.

파이썬 예제

Python에서는 requests와 pandas를 이용해 분석용 데이터로 변환할 수 있습니다.

CODE
import requests
import pandas as pd

url = "https://api.datausa.io/tesseract/data.jsonrecords"
params = {
    "cube": "acs_yg_total_population_5",
    "drilldowns": "State,Year",
    "measures": "Population",
    "include": "Year:2023",
    "limit": "100,0",
}

response = requests.get(url, params=params, timeout=30)
response.raise_for_status()

result = response.json()
frame = pd.DataFrame(result["data"])
frame = frame.sort_values("Population", ascending=False)

print(frame[["State", "Year", "Population"]].head(10))

분석 결과를 저장할 때는 조회한 cube, 필터, 조회 시점과 annotations의 출처 정보도 함께 기록하면 재현성을 높일 수 있습니다.

필터와 정렬

include에는 여러 조건을 세미콜론으로 연결할 수 있습니다.

CODE
include=Year:2023;State:04000US01

특정 값을 제외할 때는 exclude를 사용합니다. 측정값을 기준으로 결과를 제한하려면 filters를 사용할 수 있습니다.

CODE
filters=Population.gt.30000000
filters=Population.gte.250000.and.lte.750000

지원되는 비교 연산에는 gt, gte, lt, lte, eq, neq, isnull, isnotnull이 있습니다.

정렬은 sort 파라미터에 필드와 방향을 지정합니다.

CODE
sort=Population.desc

상위 N개 데이터를 구하려면 top을 활용할 수 있습니다. 이때 파라미터에서 언급하는 level과 measure가 요청의 drilldowns 또는 measures에도 포함되어야 합니다.

최신 데이터 조회

시간 차원에서 최신 값이나 일정 기간을 조회할 때는 time 파라미터를 사용할 수 있습니다.

CODE
time=Year.latest
time=Year.latest.3
time=Year.trailing.5

데이터셋마다 시간 차원의 이름과 제공 범위가 다르므로 cube 스키마를 먼저 확인하세요. 최신 데이터가 항상 현재 연도를 의미하지는 않으며 원본 기관의 발표 일정에 따라 시차가 발생할 수 있습니다.

파일로 내려받기

데이터 엔드포인트의 확장자를 변경하면 목적에 맞는 파일 형식으로 받을 수 있습니다.

  • .csv: 일반적인 데이터 분석과 스프레드시트
  • .tsv: 값에 쉼표가 많은 텍스트 데이터
  • .xlsx: Excel에서 바로 확인할 데이터
  • .parquet: 대용량 분석과 데이터 파이프라인
  • .jsonarrays: 크기가 작은 배열 중심 JSON
  • .jsonrecords: 읽기 쉬운 객체 중심 JSON

같은 쿼리를 유지하고 data.jsonrecords를 data.csv처럼 변경하면 됩니다. 대량 데이터는 JSON보다 Parquet 형식이 저장 공간과 처리 성능 면에서 유리할 수 있습니다.

활용 아이디어

지역 비교 대시보드

주 또는 카운티별 인구, 고용과 임금을 결합해 지역 비교 화면을 만들 수 있습니다. 연도별 데이터를 함께 조회하면 성장률과 장기 추세도 계산할 수 있습니다.

교육 정보 서비스

대학별 등록 인원, 전공, 졸업률, 학비와 재정 지원 데이터를 활용해 대학 및 학위 과정 비교 기능을 구성할 수 있습니다.

노동시장 분석

직업별 고용 인원, 임금과 예상 성장률을 비교해 진로 탐색이나 채용시장 분석 서비스에 활용할 수 있습니다. O*NET 기술 데이터와 결합하면 직업별 요구 역량도 함께 보여줄 수 있습니다.

시장 조사

지역별 인구통계와 산업 데이터를 이용해 잠재 시장 규모를 분석할 수 있습니다. 단, 표본조사 데이터의 오차 범위와 작은 지역 단위의 불확실성을 반드시 고려해야 합니다.

사용 시 주의점

Data USA를 사용할 때는 다음 사항을 확인해야 합니다.

  1. 표본 오차: ACS와 PUMS는 표본조사이므로 작은 지역이나 세부 집단은 오차가 커질 수 있습니다.
  2. 갱신 시차: 데이터의 기준 연도와 실제 공개 시점 사이에 차이가 있습니다.
  3. 분류 변경: 산업, 직업과 지역 분류가 연도별로 변경될 수 있습니다.
  4. 집계 방식: measure는 cube의 기본 집계 함수에 따라 자동 집계됩니다.
  5. 출처 표시: 응답의 annotations를 확인하고 원본 기관과 데이터셋을 함께 표시하는 것이 좋습니다.
  6. 공식 문서 확인: API 구조나 데이터셋은 변경될 수 있으므로 운영 전에 최신 스키마를 다시 확인해야 합니다.

특히 작은 지역이나 매우 세분화된 인구 집단을 비교할 때 단순한 수치 차이를 확정적인 사실로 해석하지 않도록 주의해야 합니다.

실무 체크리스트

  • /cubes에서 목적에 맞는 데이터셋을 찾았는가?
  • cube 스키마에서 drilldown과 measure 이름을 확인했는가?
  • /members에서 실제 필터 식별자를 확인했는가?
  • 페이지네이션과 전체 결과 수를 처리했는가?
  • 네트워크 오류와 호출 실패에 대비했는가?
  • 데이터 출처와 기준 연도를 화면에 표시했는가?
  • 캐시와 갱신 주기를 데이터 특성에 맞게 설정했는가?
  • 표본 오차와 원본 데이터의 주의사항을 검토했는가?

Data USA는 미국 공공 데이터를 하나의 방식으로 탐색할 수 있다는 점이 가장 큰 장점입니다. cube 스키마를 먼저 이해하고 출처와 집계 기준을 함께 확인한다면 지역 분석, 교육 정보, 노동시장과 시장 조사 등 다양한 서비스에 활용할 수 있습니다.