쿼리 파라미터(Query Parameter)

쿼리(Query)는 '문의' 또는 '물음표'라는 뜻을 가지고 있는데요. 쿼리 파라미터(Query Parameter)는 URL 뒤에 물음표(?)와 함께 붙는 키-값(Key-Value) 쌍입니다. 여러 개의 쿼리 파라미터를 전달하려면 파라미터 사이에 앰퍼샌드(&)를 추가해서 하나의 문자열(string)로 전달하세요. 쿼리 파라미터로는 문자열뿐만 아니라 숫자, 리스트 등 다양한 형태의 데이터를 넣을 수 있어요.

쿼리 파라미터는 다양한 용도가 있는데요. 웹 서버의 요청에 대한 추가 정보를 제공하고, 전달된 데이터로 서버가 추가 액션을 취할 수도 있어요.

위 예시에는 네 가지의 쿼리 파라미터가 들어 있어요. 첫 번째 파라미터는 paymentType이 키, NORMAL이 값이죠. 나머지 파라미터도 같은 구조로 되어 있어요.

쿼리 파라미터는 클라이언트에서 서버로 간단히 데이터를 전달하고 싶을 때 유용해요. 예를 들어, 토스페이먼츠 결제 연동에서는 클라이언트로 전달된 paymentType 쿼리 파라미터 값에 따라 서버에서 다른 API를 호출해야 돼요. 더 자세한 내용은 결제 연동하기 가이드를 참고하세요.

쿼리 파라미터는 다양한 용도로 사용할 수 있어요.

• API 요청: API 엔드포인트에 쿼리 파라미터를 붙이면 주로 결과를 조회하거나 필터링하는 데 사용돼요. 예를 들어, 토스페이먼츠 거래 조회 API는 쿼리 파라미터로 조회할 기간을 설정할 수 있어요. 아래 예시처럼 엔드포인트 URL 뒤에 startDate, endDate 키를 붙이면 되죠. Body 파라미터보다 더 간단하게 파라미터를 넘길 수 있어서 사용돼요.
• 검색: 많은 검색 엔진이 쿼리 파라미터를 사용합니다. 구글 검색 결과 페이지의 URL을 자세히 보면 쿼리 파라미터가 여러 개 붙어있는데요. 검색 쿼리를 서버에 전달하고 결과를 필터링하는 역할을 해요.
• 트래킹: 쿼리 파라미터는 어떤 경로로 방문자가 사이트를 접속하는지 트래킹하는 데도 사용돼요. 대표적으로 UTM 파라미터 방법이 있죠. 특정 링크에 UTM 파라미터를 추가해놓고 방문자의 유입경로를 간편하게 확인할 수 있어요.