웹 스크래핑 API 사용법: 초보자를 위한 안내서

첫 요청부터 구조화된 JSON까지: 테스트를 거친 Python 코드, 오류 처리, 그리고 중요한 설정값을 다루는 웹 스크래핑 API 사용 단계별 가이드입니다.

웹 스크레이핑 API는 웹 페이지를 수집하는 어려운 작업을 대신 처리해줍니다. 프록시를 선택하고, 페이지에 브라우저가 필요할 때 브라우저를 실행하고, 실패하면 재시도하고, 요청한 HTML이나 데이터를 돌려줍니다. URL과 함께 요청 하나를 보내면, 그 서비스가 당신과 사이트 사이의 모든 것을 처리합니다.

이 안내서는 Shifter의 Web Scraping API를 예로 들어, 첫 요청부터 작고 신뢰할 수 있는 스크레이퍼까지 안내합니다. 이 단계와 패턴은 이런 종류의 대부분 서비스에서 동일합니다. 요청 뒤에서 무슨 일이 일어나는지 먼저 알고 싶다면, 웹 스크레이핑 API의 작동 방식을 다룬 설명 글을 참고하세요.

1단계: API 키 받기

모든 요청은 API 키로 인증됩니다. Shifter 패널에서 Web Scraping API를 연 다음 API Keys로 이동해 활성화된 키를 복사하세요.

키는 코드 밖에 두세요. 저장소나 스크린샷에 남지 않도록 환경 변수에 저장합니다:

export SHIFTER_SCRAPER_KEY="your-key-here"

2단계: 첫 요청 보내기

이 API는 단일 엔드포인트 https://scrape.shifter.io/v1로 구성되어 있습니다. 키와 원하는 페이지를 쿼리 파라미터로 전달합니다:

curl "https://scrape.shifter.io/v1?api_key=$SHIFTER_SCRAPER_KEY&url=https://example.com"

응답은 API의 프록시를 거쳐 가져온 페이지의 HTML입니다. 기본 요청에 필요한 것은 이것이 전부입니다.

3단계: 페이지에 필요할 때 JavaScript 렌더링 켜기

많은 최신 사이트는 거의 비어 있는 페이지를 보내고, 콘텐츠는 브라우저에서 JavaScript로 만들어냅니다. 받은 HTML에 브라우저에서 보이는 데이터가 빠져 있다면 render_js=1을 추가하세요. 그러면 API가 헤드리스 브라우저에서 페이지를 로드하고 렌더링된 결과를 반환합니다. Shifter에서는 렌더링된 요청도 일반 요청과 같은 비용입니다.

느린 페이지에 도움이 되는 두 가지 관련 설정이 있습니다:

wait_for_css는 특정 요소가 나타날 때까지 기다린 뒤 반환하므로, 데이터가 로드되기 전의 페이지를 받는 일을 막아줍니다.
timeout은 느린 사이트에 더 많은 시간을 줍니다.

렌더링은 일반 가져오기보다 느리므로, 필요한 페이지에만 사용하세요. 필요 여부를 판단하는 방법은 JavaScript가 많은 사이트 스크레이핑 가이드에서 설명합니다.

4단계: HTML 대신 JSON 받기

HTML을 직접 파싱하는 것은 대부분의 스크레이퍼가 망가지는 지점입니다. 대신 extract_rules로 원하는 필드를 설명하세요. 이는 각 필드 이름을 CSS 셀렉터와 거기서 무엇을 반환할지에 매핑하는 JSON 객체입니다.

`output`	반환값
`text`	요소의 텍스트
`html`	요소의 내부 HTML
`@href`, `@src` 등	속성의 값

예를 들어 {"title": {"selector": "h1", "output": "text"}}는 example.com에서 {"title": "Example Domain"}을 반환합니다. 많은 페이지가 데이터를 이미 구조화된 JSON으로 내장하고 있기도 합니다. HTML을 파싱하는 대신 JSON-LD를 추출하기 가이드에서 사용법을 보여줍니다.

5단계: 오류를 제대로 처리하기

모든 스크레이퍼는 실패를 만납니다. 느린 사이트, 렌더링되지 않는 페이지, 한 번에 너무 많은 요청 등입니다. API는 상태 코드로 무엇이 잘못되었는지 알려주며, 올바른 대응은 받은 코드에 따라 달라집니다:

상태	의미	해야 할 일
`200`	성공	응답을 사용
`400`, `401`, `403`	요청, 키, 또는 플랜 기능에 문제가 있음	수정할 것. 재시도해도 소용없음
`408`	대상 사이트가 타임아웃됨	재시도, 필요하면 `timeout`을 더 높여서
`422`	페이지 렌더링 실패	재시도. 일반 브라우저에서 사이트가 정상 작동하는지 확인
`429`	플랜 기준 동시 요청이 너무 많음	기다렸다가 재시도
`500`	내부 오류	짧게 지연 후 재시도

Shifter에서는 실패한 요청에는 비용이 청구되지 않습니다. 성공한 응답마다 크레딧 1개를 지불합니다. API는 응답하기 전에 내부적으로 일부 실패를 재시도하기도 하는데, 이는 하나의 호출로 계산됩니다.

전체 조합하기

다섯 단계를 모두 감싸는 작은 Python 헬퍼입니다. 환경 변수에서 키를 읽고, 요청 시 렌더링과 추출을 추가하며, 재시도할 가치가 있는 오류는 점점 길어지는 지연과 함께 재시도하고, 수정이 필요한 오류는 즉시 멈춥니다.

import json
import os
import time

import requests

API = "https://scrape.shifter.io/v1"
RETRY = {408, 422, 429, 500}          # worth another try after a pause
STOP = {400, 401, 403}                # fix the request; retrying will not help


def scrape(url, render_js=False, extract_rules=None, attempts=3, session=None, wait=2.0):
    """Fetch one page through the Web Scraping API; returns text, or parsed JSON with extract_rules."""
    session = session or requests.Session()
    params = {"api_key": os.environ["SHIFTER_SCRAPER_KEY"], "url": url}
    if render_js:
        params["render_js"] = 1
    if extract_rules:
        params["extract_rules"] = json.dumps(extract_rules)
    for attempt in range(1, attempts + 1):
        response = session.get(API, params=params, timeout=120)
        if response.status_code == 200:
            return response.json() if extract_rules else response.text
        if response.status_code in STOP or attempt == attempts or response.status_code not in RETRY:
            raise RuntimeError(f"{url}: HTTP {response.status_code} {response.text[:200]}")
        time.sleep(wait * attempt)    # back off a little more each time

사용 예:

from scrape_api import scrape

html = scrape("https://example.com")
data = scrape("https://example.com", extract_rules={"title": {"selector": "h1", "output": "text"}})
print(data["title"])

이 헬퍼의 요청 구성, 재시도, 중단 조건은 위의 각 상태 코드에 대한 모의 응답으로 테스트했습니다.

재시도 로직이 처음이라면, 웹 스크레이퍼를 위한 재시도와 백오프 가이드에서 시도할 때마다 지연이 길어지는 이유를 설명합니다.

6단계: 규모 키우기

단일 요청이 작동하고 나면, 규모를 키우면서 중요한 세 가지가 있습니다:

동시성. 스레드 풀이나 비동기 클라이언트로 여러 요청을 한 번에 보내세요. 각 플랜에는 동시성 한도가 있습니다(Shifter에서는 플랜에 따라 한 번에 20개에서 500개 요청까지). 이 한도 아래로 유지하고, 429를 속도를 늦추라는 신호로 받아들이세요.
위치와 프록시 유형. country 파라미터를 사용해 특정 국가에서 보이는 대로 페이지를 가져오세요. Growth 플랜 이상에서는 premium_proxy가 데이터센터 트래픽을 차단하는 사이트를 위해 레지덴셜 IP를 통해 요청을 라우팅합니다.
세션. 여러 단계로 이루어진 흐름에서는 session_id가 요청 전반에 걸쳐 동일한 IP와 쿠키를 유지해줍니다.

데이터가 들어오기 시작하면, 조회할 수 있는 곳에 저장하세요. 웹 스크레이핑 API 데이터를 SQL로 옮기기 가이드에서 응답에서 테이블까지 깔끔한 파이프라인을 다룹니다.

초보자가 흔히 하는 실수

API 키를 하드코딩하기. 환경 변수나 비밀 관리 도구를 사용하세요.
모든 것을 렌더링하기. 먼저 일반 요청을 시도하고, 필요한 페이지만 렌더링하세요.
모든 것을 재시도하기. 401은 영원히 실패합니다. 나중에 성공할 수 있는 오류만 재시도하세요.
HTML을 손으로 파싱하기. 가능하면 추출 규칙이나 내장된 JSON을 사용하세요.
동시성 한도를 무시하기. 병렬 요청이 너무 많으면 속도가 아니라 429가 생깁니다.

FAQ

웹 스크레이핑 API란 무엇인가요?

자체 프록시와 브라우저를 통해 웹 페이지를 대신 가져오고, 재시도와 차단을 처리하며, 단일 요청에 대한 응답으로 HTML이나 추출된 데이터를 반환하는 서비스입니다.

웹 스크레이핑 API를 사용하려면 코딩을 알아야 하나요?

조금은요. 단일 요청은 curl로 명령줄에서도 작동하지만, 실제 프로젝트 대부분은 요청을 보내고, 오류를 처리하고, 결과를 저장하기 위해 Python이나 다른 언어로 된 짧은 스크립트를 사용합니다.

JavaScript 렌더링은 언제 켜야 하나요?

렌더링 없이 받은 HTML에 브라우저에서 보이는 콘텐츠가 빠져 있을 때입니다. 많은 사이트가 JavaScript로 페이지를 구성하며, 렌더링은 브라우저가 보여주는 그대로의 페이지를 반환합니다.

실패한 요청도 크레딧이 소모되나요?

Shifter에서는 아닙니다. 성공한 응답당 크레딧 1개가 청구되며, 대상 사이트에서 발생한 오류를 포함한 실패한 요청은 무료입니다.

결론

웹 스크레이핑 API를 사용하는 것은 몇 가지 습관으로 귀결됩니다: 키는 환경 변수에 보관하고, 일반 요청으로 시작해 필요한 곳에만 렌더링을 추가하고, HTML을 파싱하는 대신 추출 규칙으로 JSON을 요청하고, 나중에 성공할 수 있는 오류만 재시도하고, 플랜의 동시성을 존중하세요. 위의 헬퍼는 약 스무 줄로 이 모든 것을 다룹니다. 플랜과 한도는 Web Scraping API 가격 페이지에서 확인할 수 있습니다.