requests로 API 호출 시작하기: 파이썬 웹 데이터 수집 기본 요령

파이썬 requests 라이브러리로 웹 세상과 소통하기

파이썬을 활용해 반복 업무를 자동화하거나 외부 데이터를 수집하다 보면 웹 서버와 데이터를 주고받아야 하는 순간이 반드시 찾아옵니다. 웹 브라우저 주소창에 주소를 입력하듯, 파이썬 코드 안에서 웹 서버에 신호를 보내고 응답을 받아오는 가장 쉽고 강력한 도구가 바로 requests 라이브러리입니다. 이번 글에서는 초보자도 곧바로 실무에 적용할 수 있도록 requests를 이용해 API를 호출하고 데이터를 파악하는 기본적인 방법부터 에러를 대처하는 요령까지 차근차근 살펴보겠습니다.

[목차]

이 글을 읽고 나면 파이썬 표준 라이브러리가 아닌 외부 패키지를 설치하는 방법부터 시작해, 가장 기본적인 GET 요청을 보내고 응답 상태 코드를 확인하는 법, 그리고 JSON 형태의 응답 데이터를 파이썬 딕셔너리로 변환해 필요한 값을 추출하는 전체적인 흐름을 이해할 수 있습니다.

실무에서 requests가 사랑받는 이유

파이썬에는 기본적으로 웹 통신을 지원하는 urllib이라는 표준 라이브러리가 존재합니다. 하지만 urllib은 코드가 다소 장황하고 직관성이 떨어져 초보자가 다루기에는 진입장벽이 높습니다. 반면 requests는 인간 중심의 API를 표방하며 만들어졌기 때문에, 사람이 생각하는 방식 그대로 코드를 작성할 수 있습니다.

예를 들어 데이터를 가져오고 싶을 때는 requests.get()을 사용하고, 데이터를 전송하고 싶을 때는 requests.post()를 직관적으로 호출하면 끝납니다. 쿠키나 헤더, 파라미터 전달도 딕셔너리 형태로 간단하게 넘길 수 있어 유지보수가 쉽고 가독성이 뛰어난 스크립트를 작성할 수 있습니다.

requests 기본 설치와 환경 준비

requests는 파이썬 기본 내장 라이브러리가 아니므로 터미널이나 명령 프롬프트를 통해 별도로 설치해야 합니다. 파이썬이 설치되어 있다면 패키지 관리자인 pip 명령어를 통해 간단하게 시스템에 추가할 수 있습니다.

pip install requests

설정이 제대로 완료되었는지 확인하려면 파이썬 인터프리터를 열고 import requests를 실행했을 때 오류가 발생하지 않으면 됩니다. 가상 환경을 사용 중인 프로젝트라면 반드시 해당 가상 환경이 활성화된 상태에서 설치를 진행해야 충돌을 방지할 수 있습니다.

가장 쉬운 GET 요청과 응답 데이터 확인

API 호출의 가장 기본은 서버에 정보를 요청하는 GET 방식입니다. 공개된 테스트용 API 주소를 이용해 코드를 작성해 보겠습니다. 서버가 정상적으로 응답했는지 확인하려면 응답 객체의 status_code 속성을 살펴보아야 합니다.

import requests

url = "https://api.github.com/events"
response = requests.get(url)

print("상태 코드:", response.status_code)
if response.status_code == 200:
    print("요청 성공!")
else:
    print("요청 실패 또는 다른 상태 코드 반환")

상태 코드가 200이라는 것은 서버가 요청을 정상적으로 처리하고 데이터를 성공적으로 돌려주었다는 뜻입니다. 404는 주소가 잘못되었거나 데이터가 없는 경우이며, 500번대 코드는 서버 내부의 오류를 의미하므로 항상 상태 코드를 먼저 확인하는 습관을 들여야 합니다.

JSON 응답 데이터 다루기

대부분의 모던 웹 API는 데이터를 교환할 때 JSON 형식을 사용합니다. requests는 개발자의 편의를 위해 응답받은 JSON 문자열을 곧바로 파이썬의 리스트나 딕셔너리 자료형으로 변환해 주는 json() 메서드를 제공합니다.

import requests

url = "https://api.github.com/events"
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    # 첫 번째 이벤트의 타입 출력해보기
    print(data[0]['type'])

이렇게 변환된 데이터는 일반적인 파이썬 딕셔너리처럼 다루면 되므로, 반복문을 돌리거나 특정 키값을 추출하여 엑셀 파일로 정리하거나 데이터베이스에 저장하는 등의 후속 작업을 이어갈 수 있습니다.

쿼리 파라미터와 헤더 설정 요령

실무에서 API를 호출할 때는 단순히 주소만 넣는 경우가 드뭅니다. 검색어나 페이지 번호 같은 조건을 붙여야 하거나, API 키를 헤더에 담아 인증 절차를 거쳐야 합니다. requests에서는 이러한 복잡한 조건들을 params와 headers 인자를 통해 깔끔하게 처리할 수 있습니다.

import requests

url = "https://api.github.com/search/repositories"
params = {"q": "language:python", "sort": "stars"}
headers = {"Accept": "application/vnd.github.v3+json"}

response = requests.get(url, params=params, headers=headers)
print(response.status_code)

주소창에 직접 물음표와 기호를 붙여가며 문자열을 조합할 필요 없이, 파이썬 딕셔너리로 분리하여 전달하기 때문에 코드가 훨씬 깔끔해지고 오타 발생 확률도 줄어듭니다.

자주 하는 실수와 해결 방법

상태 코드 확인 생략: 응답이 성공했다고 가정하고 곧바로 response.json()을 호출하다가 에러가 발생하는 경우가 많습니다. 반드시 status_code == 200 조건을 먼저 검증해야 합니다.
타임아웃 설정 누락: 서버 응답이 지연될 때 스크립트가 무한정 멈춰버리는 현상을 막기 위해 timeout 인자를 필수로 지정하는 것이 안전합니다.
인증 키 노출: API 시크릿 키나 토큰을 소스 코드에 그대로 하드코딩하여 깃허브 등에 공개하는 실수를 조심해야 합니다. 환경 변수나 별도의 설정 파일을 활용하는 습관이 필요합니다.
인코딩 문제 방치: 한글 데이터가 깨져서 출력될 때는 response.encoding을 명시적으로 utf-8로 지정해 주어야 안전하게 읽어올 수 있습니다.

API 호출 스크립트 작성 점검표

실무에서 파이썬을 이용해 API 연동 스크립트를 작성할 때 반드시 확인해야 할 핵심 점검 항목입니다.

패키지 설치 확인: 가상 환경 내에 requests가 올바르게 설치되어 있는지 확인했는가?
상태 코드 분기: 200 성공 외에 4xx, 5xx 에러 상황에 대한 예외 처리가 코드에 포함되어 있는가?
타임아웃 적용: 네트워크 지연에 대비하여 timeout=(3, 5) 형태의 제한 시간을 설정했는가?
파라미터 분리: 쿼리 스트링을 문자열 연산 대신 params 딕셔너리로 깔끔하게 정리했는가?
보안 정보 분리: API 키나 비밀번호가 소스 코드에 노출되지 않고 환경 변수로 분리되었는가?
데이터 구조 파악: 응답받은 JSON 구조를 딕셔너리 키 접근 방식으로 안전하게 파싱하고 있는가?

안정적인 자동화를 위한 마무리

지금까지 파이썬 requests 라이브러리를 활용해 웹 API를 호출하고 응답을 다루는 기본적인 방법을 살펴보았습니다. 외부 서버와 통신하는 코드는 네트워크 상태나 서버의 사정에 따라 언제든지 예외 상황이 발생할 수 있습니다. 따라서 오늘 다룬 상태 코드 확인, 타임아웃 설정, 파라미터 분리 등의 기본기를 탄탄히 다져둔다면 어떠한 웹 데이터 수집 자동화 업무도 안정적으로 완성할 수 있을 것입니다.

파이썬