주소 정규화・지오코딩 API 'Staddress(スタドレス)' 개발팀입니다.

지난번('Staddress API를 curl로 호출하기')에는 macOS / Linux용으로 cURL 샘플을 이용해 API를 테스트하는 절차를 소개했습니다.

이번에는 Windows 환경에 맞춰, 추가 도구(curl / jq) 없이 작동하는 PowerShell 샘플을 사용하여 같은 흐름을 시도합니다.

이 글에서 다룰 내용은 다음과 같습니다:

• 계정 관리 화면에서 API Key 확인하기

• staddress-tools의 PowerShell 샘플 클론 및 실행 정책 확인 후 스크립트 실행하기

• usage API로 이용 현황 확인하기 - 단일 건 분석 API로 주소 1건 분석하기

• Free 계정 등록이 완료되어 있어야 함

• 계정 관리 화면에서 API Key를 확인할 수 있어야 함

• Windows에서 PowerShell 5.1 (표준) 또는 PowerShell 7+ 사용 가능해야 함 - git 사용 가능해야 함 (Git for Windows 등)

이번에 사용할 샘플 코드는 다음과 같습니다.

Invoke-RestMethod만으로 작동하므로, jq 설치는 필요 없습니다.

Staddress의 계정 관리 화면을 열고, 화면 하단의 엔드포인트란에서 다음을 확인합니다.

• API Key (복사 버튼으로 획득) - API 도메인 (https://api.staddress.com)

API Key는 API 호출 시 X-Api-Key 헤더에 설정해야 합니다.

X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx

주의: API Key는 비밀번호와 마찬가지로 기밀 정보입니다. Qiita, GitHub, Slack 등에 붙여넣지 않도록 주의해 주세요.

git clone https://github.com/StaddressAI/staddress-tools.git
cd staddress-tools\examples\powershell

내용물은 다음과 같은 구성입니다.

examples/powershell/
├── README.md
├── batch-sample.json
...

이번에 사용할 것은 staddress.ps1입니다.

작업	명령어	API
이용 현황 확인	. ext{staddress.ps1 -Usage}	GET /api/v1/usage
단일 건 분석	`. ext{staddress.ps1 -Single

리포지토리 루트에 .env를 놓는 방법도 있습니다.

Copy-Item ..\..\.env.example ..\..\.env
# ..\..\.env 를 편집하여 STADDRESS_API_KEY / STADDRESS_BASE_URL 을 설정
.\staddress.ps1 -Usage

.env는 UTF-8로 저장해 주세요(문자 깨짐 방지).

우선, API Key가 제대로 사용되는지 이용 현황 API로 확인합니다.

.\staddress.ps1 -Usage

성공하면 계정 정보와 이용 현황이 JSON으로 반환됩니다.

{
"account": {
"plan": "free",
...

Free 플랜에서는 월간 분석 상한이 표시됩니다.

다음으로, 주소를 1건 분석해 보겠습니다.

.\staddress.ps1 -Single "로쿠몬기 힐즈 모리 타워 52F"

우편번호를 알고 있는 경우에는 -PostalCode를 붙입니다.

.\staddress.ps1 -Single "도쿄도 시부야구 도겐자카1-2 맨션 사쿠라 101호" -PostalCode "150-0043"

내부적으로는 다음 API를 호출하고 있습니다.

POST /api/v1/addresses/parse
X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

요청 본문은 다음과 같은 형태입니다.

{
"input": "로쿠몬기 힐즈 모리 타워 52F"
}

응답 해석( normalized / components / confidence 등)은 이전 기사의 '응답에서 봐야 할 포인트'와 동일합니다. Windows에서도 반환되는 JSON 구조는 변하지 않습니다.

관점	curl (이전)	PowerShell (이번)
주요 환경	macOS / Linux / WSL	Windows
추가 도구	curl + jq 권장	불필요 (Invoke-RestMethod)
스크립트	staddress.sh	staddress.ps1
이용 현황	-u / --usage	-Usage
단건 분석	-s "주소"	-Single "주소"
문자 깨짐 대책	셸의 로케일에 의존하기 어려움	요청 본문을 UTF-8로 전송 (Windows PowerShell 5.1용)

어떤 샘플도 호출하는 API(usage / 단건 분석 / 일괄 분석)는 동일합니다.

회사 내부가 Windows 중심이라면 이번의 PowerShell을, macOS / Linux라면 이전의 curl을 선택하는 것이 도입하기 쉽습니다.

다음과 같이 하여 현재 세션만 허용할 수 있습니다.

powershell -ExecutionPolicy Bypass -File .\staddress.ps1 -Usage

API Key가 미설정되었거나 잘못되었을 수 있습니다.

echo $env:STADDRESS_API_KEY

표시되지 않는 경우, 환경 변수를 다시 설정해 주세요.

.env나 일괄 분석용 JSON은 UTF-8로 저장해 주세요.

staddress.ps1은 Windows PowerShell 5.1을 위해 요청 본문을 UTF-8 바이트 배열로 변환하여 전송하고 있습니다.

환경 변수가 설정되지 않은 상태입니다.

$env:STADDRESS_BASE_URL = "https://api.staddress.com"

단건 분석의 input은 최대 100자입니다. 회사명, 부서명, 수신명 등이 섞여 있는 경우에는 주소란과 수신명란을 분리하는 설계를 추천합니다.

이번에는 Windows PowerShell에서 Staddress API를 호출하는 절차를 소개했습니다.

• 추가 도구 없이 Windows 표준 PowerShell 5.1 / PowerShell 7+에서 시도 가능
• staddress-tools의 examples/powershell/staddress.ps1에서 사용법(usage)과 단일 건 분석을 바로 시도할 수 있습니다 - 실행 정책으로 차단되면 -ExecutionPolicy Bypass를 사용합니다 - 응답 확인 방법은 curl 편과 동일합니다
• API Key는 비밀 정보로 취급하여 화면 공유, 기사, GitHub 등에 게시하지 않습니다.

다음 시간에는 EC/물류 SaaS를 위한 배송지 주소를 어느 타이밍에 정규화할 것인지 구현 패턴으로 정리하겠습니다.

Staddress 관련 공식 링크 목록입니다.