Naver Open API (Search, Papago, Clova)

Warnings

• gotcha Two different base URLs serve different API categories. Search and Login APIs use 'https://openapi.naver.com'. AI/ML services (Papago translation, Clova OCR, CLOVA Speech) use 'https://naveropenapi.apigw.ntruss.com'. Using the wrong base URL returns a 404 or auth error with no indication of the actual problem.
  Fix: Search/Blog/News/Login → openapi.naver.com. Papago/Clova/OCR → naveropenapi.apigw.ntruss.com. Check each service's API guide for the exact endpoint.
• gotcha Daily quota resets at 00:00 KST (Korea Standard Time, UTC+9), not UTC. If you're in UTC or UTC-8, your quota resets at 15:00 or 08:00 UTC respectively — not midnight local time. Rate limit errors return HTTP 429.
  Fix: Plan quota-sensitive workloads around KST midnight. Monitor usage via the Naver Cloud Platform console which displays usage in KST.
• gotcha Registering an application in the console does not automatically enable all APIs. Each service must be explicitly selected/enabled per application via the console Edit Application flow. Calling an API that hasn't been enabled for the application returns HTTP 429 (Quota Exceed) — not a 403 or 401 — which makes the error appear to be a rate limit issue rather than a misconfiguration.
  Fix: After registering an app, go to Edit Application and explicitly select each API service you intend to use. If you receive 429 immediately on a fresh app with no prior calls, this is the cause.
• gotcha No official Python SDK exists. Community packages on PyPI (napit, NaverTTS) are unmaintained and target old API versions. LLM-generated code often invents a 'naver' or 'naver-sdk' package that does not exist.
  Fix: Use raw requests. The API is simple enough that a direct HTTP wrapper is 10-20 lines. Reference the official API guide at api.ncloud-docs.com for exact endpoint paths and parameters.
• gotcha Search API pagination is limited: maximum 1000 results total (start + display ≤ 1001), maximum 100 results per page. Attempting to paginate beyond this returns an error. There is no cursor-based pagination.
  Fix: For large result sets, use multiple queries with different sort orders (sim/date) or date range filters to work around the 1000-result cap.
• gotcha Naver Open API registration, console UI, and official documentation are primarily in Korean. The English documentation at api.ncloud-docs.com is a translation that lags behind the Korean source and may be incomplete for newer services.
  Fix: Use the Korean documentation at developers.naver.com as the source of truth for the most current API specs. Use DeepL or Papago itself to translate if needed.
• gotcha Naver Search API returns Korean-language content by default. The API does not filter by language — all results are from Naver's Korean index. Non-Korean queries return results but content will be predominantly Korean.
  Fix: For Korean market research and Korean-language content, this is the correct tool. For multilingual or global search, use a different API.

Install

• pip install requests Only dependency needed — Naver Open API has no official Python SDK

Imports

• requests

  import requests

  There is no official Naver Python SDK on PyPI. Community packages like 'napit' or 'NaverTTS' exist but are unmaintained. Use raw requests against openapi.naver.com or naveropenapi.apigw.ntruss.com depending on the service.

Quickstart

Two different base URLs are used depending on the service: 'openapi.naver.com' for Search and Login APIs, 'naveropenapi.apigw.ntruss.com' for AI services (Papago, Clova). Using the wrong base URL returns a 404 with no helpful error message. Daily quota resets at midnight KST (UTC+9), not UTC.

import os
import requests

CLIENT_ID = os.environ['NAVER_CLIENT_ID']        # X-NCP-APIGW-API-KEY-ID
CLIENT_SECRET = os.environ['NAVER_CLIENT_SECRET']  # X-NCP-APIGW-API-KEY

headers = {
    'X-NCP-APIGW-API-KEY-ID': CLIENT_ID,
    'X-NCP-APIGW-API-KEY': CLIENT_SECRET,
}

# --- Search API (blog, news, web, image, shopping, book) ---
# Base URL: https://openapi.naver.com/v1/search/{type}.json
def search_blog(query: str, display: int = 10, start: int = 1):
    url = 'https://openapi.naver.com/v1/search/blog.json'
    params = {
        'query': query,
        'display': display,  # 1-100, default 10
        'start': start,      # 1-1000
        'sort': 'sim',       # 'sim' (relevance) or 'date'
    }
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

def search_news(query: str):
    url = 'https://openapi.naver.com/v1/search/news.json'
    params = {'query': query, 'display': 10, 'sort': 'date'}
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# --- Papago Translation ---
# Supported language pairs: ko<->en, ko<->zh-CN, ko<->zh-TW, ko<->ja, ko<->es, ko<->fr, etc.
def translate(text: str, source: str = 'ko', target: str = 'en'):
    url = 'https://naveropenapi.apigw.ntruss.com/nmt/v1/translation'
    # NOTE: Papago uses different base URL than Search API
    data = {
        'source': source,
        'target': target,
        'text': text,
    }
    response = requests.post(url, headers=headers, data=data)
    response.raise_for_status()
    return response.json()['message']['result']['translatedText']

# --- Clova OCR ---
def ocr_image(image_url: str):
    url = 'https://naveropenapi.apigw.ntruss.com/ocr/v1/recognize'
    data = {
        'image': image_url,
        'lang': 'ko',
        'type': 'url',
    }
    response = requests.post(url, headers=headers, data=data)
    response.raise_for_status()
    return response.json()

# --- Naver Login (OAuth 2.0) ---
# Step 1: Redirect user to Naver auth URL
import urllib.parse

def get_naver_login_url(state: str) -> str:
    params = {
        'response_type': 'code',
        'client_id': CLIENT_ID,
        'redirect_uri': 'https://yourdomain.com/callback',
        'state': state,
    }
    return 'https://nid.naver.com/oauth2.0/authorize?' + urllib.parse.urlencode(params)

# Step 2: Exchange code for token
def get_naver_token(code: str, state: str) -> dict:
    url = 'https://nid.naver.com/oauth2.0/token'
    params = {
        'grant_type': 'authorization_code',
        'client_id': CLIENT_ID,
        'client_secret': CLIENT_SECRET,
        'code': code,
        'state': state,
    }
    response = requests.get(url, params=params)
    return response.json()

# Step 3: Get user profile
def get_naver_profile(access_token: str) -> dict:
    url = 'https://openapi.naver.com/v1/nid/me'
    headers_auth = {'Authorization': f'Bearer {access_token}'}
    response = requests.get(url, headers=headers_auth)
    return response.json()