시작하기

빠른 시작

1. 계정 만들기

apinoa.com에서 가입하고 이메일 주소를 인증합니다. 카드는 필요하지 않습니다.

2. 크레딧 충전

호출은 선불 잔액에서 가격 페이지의 요율로 과금됩니다. 고를 요금제는 없습니다. 대시보드 > 잔액에서 남은 금액을 확인하고 충전합니다. 먼저 평가해 보려면 대시보드의 무료 크레딧 카드에서 무료 크레딧을 신청하세요. 무료 크레딧은 계정당 모두 합쳐 $1까지이며, 3단계의 $0.10도 여기에 포함됩니다.

3. API 키 만들기

가장 빠른 방법은 터미널입니다. 프로젝트 디렉터리에서 실행하세요.

npx apinoa-mcp login

열리는 페이지에서 apinoa에 로그인하고(계정이 없으면 새로 만들고), 터미널에 표시된 코드를 입력해 승인하면 키가 .env에 APINOA_API_KEY로 저장됩니다. 이 방법이나 호스팅 MCP 서버 로그인으로 처음 받는 키에는 $0.10 평가용 크레딧이 지급됩니다(계정당 한 번). 자세한 내용은 인증에 있습니다.

또는 대시보드 > API 키에서 키를 만듭니다. 키는 생성할 때 한 번만 표시되므로 바로 저장하세요.

export APINOA_API_KEY="myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

키 하나로 모든 API를 씁니다. 이 문서의 예제는 키를 환경 변수 APINOA_API_KEY에서 읽습니다. 위처럼 export하거나, npx apinoa-mcp login이 저장한 .env를 불러오세요.

4. 첫 호출 보내기

curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"

SDK는 모든 오퍼레이션을 감싸고, MCP 서버는 Claude Code, Codex, Cursor에 API 전체를 줍니다.

5. 응답 읽기

모든 응답에는 success가 있고, 그다음에 data(또는 error)가 옵니다. 검색은 SearchResult를 돌려줍니다. 줄이면 다음과 같습니다.

{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 47, "total": 4871 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "344144554",
        "title": "Genuine Dickies Men's Wool Thermal Crew Sock, 3 Pack, Shoe Size 6-12",
        "price": { "currency": "USD", "amount": 15.98 },
        "rating": { "average": 4.7, "count": 551 },
        "inStock": true
      }
    ]
  }
}

6. 플랫폼 바꾸기

플랫폼은 경로의 한 구간입니다. 키, 파라미터 이름, 응답 형태는 그대로입니다.

curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/shopify/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"

공통 규칙

이 문서의 모든 엔드포인트에 해당합니다.

기본 URL

https://gateway.apinoa.com/v1/{platform}/{operation}

{platform}은 마켓플레이스(amazon, walmart, shopify, tiktokshop, aliexpress), 소셜 플랫폼(tiktok, instagram, youtube, reddit, x, threads, linkedin), 검색엔진(google, bing, naver와 그 밖의 엔진), AI 답변 엔진(chatgpt, gemini, google-aio, google-ai-mode, naver-ai-brief, naver-ai-tab) 중 하나입니다. {operation}은 소문자이며 단어는 하이픈으로 잇습니다 (image-search). GET /v1/marketplaces가 모든 플랫폼과 오퍼레이션을 나열합니다.

GET 또는 POST

모든 오퍼레이션은 파라미터를 GET의 쿼리 문자열로도, POST의 JSON 본문으로도 받습니다. 둘은 같습니다. 예외는 이미지 검색과 AI 답변입니다. 이미지는 URL에 들어가지 않으므로 이미지 검색은 POST만 받고, AI 답변은 입력을 JSON 본문으로 받습니다.

curl -X POST "https://gateway.apinoa.com/v1/walmart/search" \
  -H "x-api-key: $APINOA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query": "wool socks", "priceMax": 30}'

알 수 없는 파라미터는 조용히 무시되지 않고, 그 이름을 밝힌 400이 됩니다.

응답 봉투

모든 응답은 success와, 그다음 data 또는 error가 담긴 JSON입니다.

{
  "success": false,
  "error": { "code": "INVALID_PARAMS", "message": "(root): Unrecognized key(s) in object: 'nope'" },
  "requestId": "8d76f93c85cc4e9f911e2d0de23334c4"
}

error.code는 바뀌지 않으며 Errors에 정리되어 있습니다. error.message는 사람이 읽는 용도입니다. 고객 지원에 문의할 때는 requestId(x-request-id 헤더로도 보냅니다)를 알려 주세요.

응답 헤더

없으면 알 수 없음

플랫폼이 밝히지 않은 필드는 기본값으로 채우지 않고 생략합니다. price가 없으면 0이 아니고, metrics.likes가 없으면 좋아요 0개가 아니라 숨겨진 수입니다. 가격은 주 통화 단위의 소수 금액(12.97)이며 통화가 함께 옵니다. 시각은 UTC 기준 ISO 8601입니다.

페이지네이션

목록은 한 페이지로 응답합니다. 오퍼레이션에 따라 다음 페이지는 이렇게 요청합니다.

• page — 1부터 시작하는 페이지 번호. 번호로 페이지를 넘기는 오퍼레이션(대부분의 마켓플레이스 검색)에서 씁니다.
• cursor — 이전 페이지가 돌려준 cursor. 커서로 페이지를 넘기는 오퍼레이션(Shopify, 모든 SNS 목록)에서 씁니다. 단독으로 넘기세요. 첫 호출에서 요청한 모든 것이 담겨 있습니다. 응답에 cursor가 없으면 다음 페이지가 없습니다.

각 엔드포인트의 파라미터 표에 어느 쪽을 받는지 나와 있습니다.

가격

각 호출은 그 API의 단가로 단위당 과금됩니다. API별 가격은 Pricing에, 호출 한 번의 가격은 각 엔드포인트 페이지에 나와 있습니다. 하루 1,000회를 넘으면 요율이 단계적으로 내려갑니다. 대부분의 호출은 1단위입니다. 더 비쌀 수 있는 경우는 각 엔드포인트의 가격 섹션에 나와 있습니다. 실패한 호출은 과금되지 않습니다.

다음 단계

• Marketplace API: 공통 오퍼레이션과 마켓플레이스별 지원 범위
• SNS API: 7개 플랫폼에 걸친 공통 오퍼레이션 8개
• SERP API: 검색엔진 16곳의 검색 결과 페이지를 하나의 스키마로
• AI Answers API: ChatGPT, Gemini, Google, Naver의 AI가 프롬프트에 내놓는 답변
• SDK와 MCP: TypeScript, Python, MCP 서버, OpenAPI 문서
• Image Translate: 상품 이미지 속 텍스트 번역
• Authentication: 키를 보내고 보호하는 법
• Errors: 모든 에러 코드와 대처 방법