openapi: 3.0.0
info:
  title: Naver News API
  description: >-
    Search Naver News, the news tab of South Korea's Naver search, with sort, time period and custom date range,
    press and article type filters. Each result has its headline, outlet and date. Optional fields include the snippet, the outlet's
    link, logo and Naver press code, the print edition page, a thumbnail, the article's Naver News copy, and the related
    articles Naver groups under it, 10 per page for up to 2,000 results. Pass a result's press_id back as the press_id parameter to search
    that outlet only.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Naver News Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to naver_news.
        schema:
          type: string
          enum: ["naver_news"]
      - name: q
        in: query
        required: true
        description: Search terms used to find news articles. Korean, English and other languages are supported.
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        description: Order of the results.
        schema:
          type: string
          enum: ["relevance","most_recent","oldest"]
          default: "relevance"
      - name: time_period
        in: query
        required: false
        description: Filter by how recently the article was published.
        schema:
          type: string
          enum: ["last_hour","last_2_hours","last_3_hours","last_4_hours","last_5_hours","last_6_hours","last_day","last_week","last_month","last_3_months","last_6_months","last_year"]
      - name: time_period_min
        in: query
        required: false
        description: Start date of a custom date range in MM/DD/YYYY format, between 01/01/1990 and today in Korea. It takes precedence over time_period.
        schema:
          type: string
          pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
      - name: time_period_max
        in: query
        required: false
        description: End date of a custom date range in MM/DD/YYYY format, between 01/01/1990 and today in Korea. It takes precedence over time_period.
        schema:
          type: string
          pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
      - name: press_id
        in: query
        required: false
        description: Naver press code of the one outlet to search, such as 1032 for 경향신문. The docs list every code.
        schema:
          type: string
          enum: ["1001","1002","1003","1004","1005","1006","1007","1008","1009","1011","1014","1015","1016","1018","1019","1020","1021","1022","1023","1024","1025","1028","1029","1030","1031","1032","1033","1036","1037","1042","1044","1047","1049","1050","1052","1053","1055","1056","1064","1065","1076","1079","1081","1082","1087","1088","1092","1094","1108","1109","1112","1117","1119","1123","1127","1138","1139","1140","1143","1144","1145","1152","1154","1156","1208","1213","1214","1216","1224","1225","1236","1241","1242","1243","1260","1262","1264","1277","1293","1295","1296","1305","1307","1308","1310","1311","1312","1321","1343","1346","1347","1348","1351","1352","1353","1356","1358","1360","1366","1371","1374","1380","1381","1382","1396","1398","1408","1409","1410","1411","1413","1415","1416","1417","1420","1421","1422","1425","1426","1427","1430","1431","1433","1435","1436","1437","1438","1439","1440","1441","1442","1445","1447","1448","1449","1450","1451","1452","1459","1460","1464","1465","1468","1469","1470","1472","1477","1481","1483","1485","1486","1487","1488","1489","1491","1494","1495","1496","1502","1511","1512","1513","1516","1517","1520","1522","1529","1531","1537","1538","1540","1544","1545","1547","1548","1550","1552","1554","1556","1557","1560","1561","1564","1566","1568","1569","1570","1571","1572","1573","1580","1584","1586","1587","1589","1590","1591","1592","1593","1594","1597","1598","1599","1600","1601","1602","1603","1605","1606","1607","1608","1609","1610","1611","1612","1613","1614","1615","1616","1617","1618","1619","1620","1621","1622","1623","1624","1625","1626","1627","1628","1629","1631","1632","1633","1634","1636","1637","1638","1640","1641","1642","1644","1645","1646","1647","1648","1649","1650","1651","1652","1653","1654","1655","1656","1657","1658","1659","1660","1661","1662","1663","1664","1665","1666","1667","1668","2001","2002","2003","2005","2007","2010","2015","2016","2017","2018","2019","2023","2024","2025","2027","2029","2030","2036","2038","2040","2041","2042","2043","2046","2047","2048","2052","2055","2056","2060","2065","2066","2067","2069","2070","2071","2073","2075","2078","2081","2083","2085","2087","2088","2090","2091","2093","2094","2095","2096","2097","2098","2099","2100","2102","2108","2110","2111","2116","2118","2119","2120","2122","2125","2126","2127","2133","2134","2136","2137","2138","2140","2141","2144","2147","2148","2149","2150","2151","2153","2154","2155","2157","2158","2159","2160","2161","2163","2167","2174","2175","2176","2177","2178","2179","2180","2184","2185","2186","2187","2188","2189","2190","2191","2192","2193","2194","2197","2198","2199","2201","2202","2203","2204","2206","2207","2208","2209","2210","2213","2214","2216","2217","2218","2221","2224","2225","2226","2227","2229","2231","2232","2233","2234","2235","2237","2238","2239","2242","2243","2244","2245","2246","2248","2249","2251","2252","2254","2256","2257","2258","2259","2260","2263","2264","2265","2267","2268","2269","2270","2271","2272","2273","2274","2275","2277","2278","2279","2281","2282","2283","2285","2286","2287","2288","2289","2290","2291","2292","2293","2294","2295","2296","2297","2298","2300","2301","2302","2303","2304","2305","2306","2307","2308","2309","2310","2312","2313","2314","2315","2318","2321","2322","2323","2324","2325","2328","2329","2330","2331","2332","2334","2335","2336","2337","2338","2339","2340","2341","2343","2344","2345","2346","2347","2348","2349","2350","2351","2352","2353","2356","2357","2358","2359","2360","2364","2366","2367","2368","2369","2370","2371","2372","2373","2374","2375","2376","2377","2378","2379","2381","2383","2384","2385","2387","2388","2389","2390","2391","2392","2393","2394","2395","2396","2397","2398","2399","2400","2401","2402","2404","2405","2407","2409","2411","2412","2413","2414","2415","2416","2417","2419","2420","2421","2422","2423","2424","2426","2427","2428","2429","2430","2431","2433","2434","2435","2436","2438","2439","2441","2442","2443","2445","2447","2448","2449","2451","2452","2454","2455","2456","2457","2458","2460","2461","2462","2464","2465","2466","2469","2470","2471","2472","2473","2474","2475","2476","2477","2479","2480","2481","2482","2483","2484","2486","2487","2488","2489","2490","2491","2492","2493","2495","2496","2497","2498","2499","2501","2503","2504","2505","2506","2507","2510","2511","2512","2513","2515","2516","2517","2518","2519","2520","2521","2522","2523","2524","2525","2526","2527","2528","2530","2533","2534","2537","2538","2539","2541","2542","2543","2544","2545","2546","2547","2548","2549","2550","2551","2552","2553","2554","2555","2556","2557","2558","2559","2560","2561","2562","2563","2565","2566","2567","2568","2569","2570","2571","2572","2573","2574","2575","2576","2577","2578","2579","2580","2581","2583","2584","2585","2586","2588","2589","2590","2591","2594","2595","2596","2597","2598","2599","2602","2603","2604","2605","2606","2609","2611","2613","2614","2616","2618","2619","2620","2621","2622","2625","2626","2628","2630","2631","2632","2633","2634","2635","2636","2637","2638","2639","2640","2641","2643","2644","2645","2646","2647","2648","2649","2650","2651","2652","2653","2656","2657","2658","2660","2661","2662","2663","2664","2665","2666","2667","2668","2670","2672","2673","2674","2675","2676","2677","2678","2679","2680","2681","2682","2683","2684","2685","2686","2687","2688","2690","2691","2692","2693","2694","2695","2697","2698","2699","2701","2703","2704","2705","2708","2709","2711","2712","2713","2714","2715","2716","2717","2718","2720","2721","2723","2724","2726","2727","2728","2729","2730","2731","2732","2733","2734","2735","2736","2738","2739","2740","2741","2742","2743","2744","2745","2746","2747","2748","2749","2750","2751","2752","2753","2754","2755","2757","2759","2760","2762","2763","2764","2767","2770","2771","2772","2773","2774","2775","2776","2777","2778","2779","2780","2781","2784","2785","2786","2787","2788","2789","2790","2791","2792","2793","2794","2795","2796","2798","2799","2800","2801","2802","2804","2805","2806","2807","2808","2809","2810","2811","2812","2813","2814","2815","2816","2817","2818","2819","2820","2821","2822","2823","2824","2825","2826","2827","2828","2829","2830","2831","2832","2833","2834","2835","2838","2839","2840","2842","2844","2845","2846","2847","2848","2849","2851","2852","2853","2854","2855","2856","2857","2858","2859","2860","2861","2862","2863","2864","2865","2866","2867","2868","2869","2870","2871","2872","2873","2874","2875","2876","2877","2878","2879","2880","2881","2882","2883","2884","2885","2886","2887","2888","2889","2890","2891","2892","2893","2894","2895","2896","2897","2898","2899","2900","2901","2902","2903","2904","2905","2906","2907","2908","2909","2910","2911","2912","2913","2914","2915","2916","2917","2919","2920","2921","2922","2923"]
      - name: article_type
        in: query
        required: false
        description: Filter by kind of article.
        schema:
          type: string
          enum: ["video","print","press_release","auto_generated"]
      - name: page
        in: query
        required: false
        description: Page of results to return, starting at 1. Each page has 10 results, and Naver returns up to 2,000.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: >-
            Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting
            for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        organic_results:
          type: array
          items:
            "$ref": "#/components/schemas/OrganicResult"
        pagination:
          "$ref": "#/components/schemas/Pagination"
        error:
          type: string
          description: Message describing an empty result set or a page past the last result.
    SearchMetadata:
      type: object
      required:
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Naver News URL for this search
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          enum: ["naver_news"]
          description: Set to naver_news.
        q:
          type: string
          description: Search terms used to find news articles.
        sort_by:
          type: string
          enum: ["relevance","most_recent","oldest"]
          description: Order of the results.
        time_period:
          type: string
          enum: ["last_hour","last_2_hours","last_3_hours","last_4_hours","last_5_hours","last_6_hours","last_day","last_week","last_month","last_3_months","last_6_months","last_year"]
          description: Filter by how recently the article was published.
        time_period_min:
          type: string
          pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
          description: Start date of the custom date range in MM/DD/YYYY format.
        time_period_max:
          type: string
          pattern: '^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/(19|20)\d\d$'
          description: End date of the custom date range in MM/DD/YYYY format.
        press_id:
          type: string
          enum: ["1001","1002","1003","1004","1005","1006","1007","1008","1009","1011","1014","1015","1016","1018","1019","1020","1021","1022","1023","1024","1025","1028","1029","1030","1031","1032","1033","1036","1037","1042","1044","1047","1049","1050","1052","1053","1055","1056","1064","1065","1076","1079","1081","1082","1087","1088","1092","1094","1108","1109","1112","1117","1119","1123","1127","1138","1139","1140","1143","1144","1145","1152","1154","1156","1208","1213","1214","1216","1224","1225","1236","1241","1242","1243","1260","1262","1264","1277","1293","1295","1296","1305","1307","1308","1310","1311","1312","1321","1343","1346","1347","1348","1351","1352","1353","1356","1358","1360","1366","1371","1374","1380","1381","1382","1396","1398","1408","1409","1410","1411","1413","1415","1416","1417","1420","1421","1422","1425","1426","1427","1430","1431","1433","1435","1436","1437","1438","1439","1440","1441","1442","1445","1447","1448","1449","1450","1451","1452","1459","1460","1464","1465","1468","1469","1470","1472","1477","1481","1483","1485","1486","1487","1488","1489","1491","1494","1495","1496","1502","1511","1512","1513","1516","1517","1520","1522","1529","1531","1537","1538","1540","1544","1545","1547","1548","1550","1552","1554","1556","1557","1560","1561","1564","1566","1568","1569","1570","1571","1572","1573","1580","1584","1586","1587","1589","1590","1591","1592","1593","1594","1597","1598","1599","1600","1601","1602","1603","1605","1606","1607","1608","1609","1610","1611","1612","1613","1614","1615","1616","1617","1618","1619","1620","1621","1622","1623","1624","1625","1626","1627","1628","1629","1631","1632","1633","1634","1636","1637","1638","1640","1641","1642","1644","1645","1646","1647","1648","1649","1650","1651","1652","1653","1654","1655","1656","1657","1658","1659","1660","1661","1662","1663","1664","1665","1666","1667","1668","2001","2002","2003","2005","2007","2010","2015","2016","2017","2018","2019","2023","2024","2025","2027","2029","2030","2036","2038","2040","2041","2042","2043","2046","2047","2048","2052","2055","2056","2060","2065","2066","2067","2069","2070","2071","2073","2075","2078","2081","2083","2085","2087","2088","2090","2091","2093","2094","2095","2096","2097","2098","2099","2100","2102","2108","2110","2111","2116","2118","2119","2120","2122","2125","2126","2127","2133","2134","2136","2137","2138","2140","2141","2144","2147","2148","2149","2150","2151","2153","2154","2155","2157","2158","2159","2160","2161","2163","2167","2174","2175","2176","2177","2178","2179","2180","2184","2185","2186","2187","2188","2189","2190","2191","2192","2193","2194","2197","2198","2199","2201","2202","2203","2204","2206","2207","2208","2209","2210","2213","2214","2216","2217","2218","2221","2224","2225","2226","2227","2229","2231","2232","2233","2234","2235","2237","2238","2239","2242","2243","2244","2245","2246","2248","2249","2251","2252","2254","2256","2257","2258","2259","2260","2263","2264","2265","2267","2268","2269","2270","2271","2272","2273","2274","2275","2277","2278","2279","2281","2282","2283","2285","2286","2287","2288","2289","2290","2291","2292","2293","2294","2295","2296","2297","2298","2300","2301","2302","2303","2304","2305","2306","2307","2308","2309","2310","2312","2313","2314","2315","2318","2321","2322","2323","2324","2325","2328","2329","2330","2331","2332","2334","2335","2336","2337","2338","2339","2340","2341","2343","2344","2345","2346","2347","2348","2349","2350","2351","2352","2353","2356","2357","2358","2359","2360","2364","2366","2367","2368","2369","2370","2371","2372","2373","2374","2375","2376","2377","2378","2379","2381","2383","2384","2385","2387","2388","2389","2390","2391","2392","2393","2394","2395","2396","2397","2398","2399","2400","2401","2402","2404","2405","2407","2409","2411","2412","2413","2414","2415","2416","2417","2419","2420","2421","2422","2423","2424","2426","2427","2428","2429","2430","2431","2433","2434","2435","2436","2438","2439","2441","2442","2443","2445","2447","2448","2449","2451","2452","2454","2455","2456","2457","2458","2460","2461","2462","2464","2465","2466","2469","2470","2471","2472","2473","2474","2475","2476","2477","2479","2480","2481","2482","2483","2484","2486","2487","2488","2489","2490","2491","2492","2493","2495","2496","2497","2498","2499","2501","2503","2504","2505","2506","2507","2510","2511","2512","2513","2515","2516","2517","2518","2519","2520","2521","2522","2523","2524","2525","2526","2527","2528","2530","2533","2534","2537","2538","2539","2541","2542","2543","2544","2545","2546","2547","2548","2549","2550","2551","2552","2553","2554","2555","2556","2557","2558","2559","2560","2561","2562","2563","2565","2566","2567","2568","2569","2570","2571","2572","2573","2574","2575","2576","2577","2578","2579","2580","2581","2583","2584","2585","2586","2588","2589","2590","2591","2594","2595","2596","2597","2598","2599","2602","2603","2604","2605","2606","2609","2611","2613","2614","2616","2618","2619","2620","2621","2622","2625","2626","2628","2630","2631","2632","2633","2634","2635","2636","2637","2638","2639","2640","2641","2643","2644","2645","2646","2647","2648","2649","2650","2651","2652","2653","2656","2657","2658","2660","2661","2662","2663","2664","2665","2666","2667","2668","2670","2672","2673","2674","2675","2676","2677","2678","2679","2680","2681","2682","2683","2684","2685","2686","2687","2688","2690","2691","2692","2693","2694","2695","2697","2698","2699","2701","2703","2704","2705","2708","2709","2711","2712","2713","2714","2715","2716","2717","2718","2720","2721","2723","2724","2726","2727","2728","2729","2730","2731","2732","2733","2734","2735","2736","2738","2739","2740","2741","2742","2743","2744","2745","2746","2747","2748","2749","2750","2751","2752","2753","2754","2755","2757","2759","2760","2762","2763","2764","2767","2770","2771","2772","2773","2774","2775","2776","2777","2778","2779","2780","2781","2784","2785","2786","2787","2788","2789","2790","2791","2792","2793","2794","2795","2796","2798","2799","2800","2801","2802","2804","2805","2806","2807","2808","2809","2810","2811","2812","2813","2814","2815","2816","2817","2818","2819","2820","2821","2822","2823","2824","2825","2826","2827","2828","2829","2830","2831","2832","2833","2834","2835","2838","2839","2840","2842","2844","2845","2846","2847","2848","2849","2851","2852","2853","2854","2855","2856","2857","2858","2859","2860","2861","2862","2863","2864","2865","2866","2867","2868","2869","2870","2871","2872","2873","2874","2875","2876","2877","2878","2879","2880","2881","2882","2883","2884","2885","2886","2887","2888","2889","2890","2891","2892","2893","2894","2895","2896","2897","2898","2899","2900","2901","2902","2903","2904","2905","2906","2907","2908","2909","2910","2911","2912","2913","2914","2915","2916","2917","2919","2920","2921","2922","2923"]
          description: Naver press code of the outlet searched.
        article_type:
          type: string
          enum: ["video","print","press_release","auto_generated"]
          description: Filter by kind of article.
        page:
          type: integer
          minimum: 1
          maximum: 200
          description: Page of results returned, starting at 1.
    OrganicResult:
      type: object
      required:
      - position
      - title
      - link
      - source
      - date
      properties:
        position:
          type: integer
          description: Position of the article in the results, counting from the first page.
        title:
          type: string
          description: Headline of the article, which Naver shortens with an ellipsis when it is long.
        link:
          type: string
          description: URL of the article on the outlet's website.
        source:
          type: string
          description: Name of the outlet that published the article.
        source_link:
          type: string
          description: URL of the outlet's page on Naver News or of its own website.
        press_id:
          type: string
          description: Naver press code of the outlet, accepted by the press_id parameter.
        favicon:
          type: string
          description: Logo URL of the outlet.
        date:
          type: string
          description: Publication date as Naver shows it, a relative age such as 3시간 전 or a date such as 2026.10.07.
        newspaper_page:
          type: string
          description: Print edition page and column the article ran in, such as A12면 1단.
        snippet:
          type: string
          description: Excerpt of the article text.
        thumbnail:
          type: string
          description: Thumbnail URL of the article's image or video.
        naver_news_link:
          type: string
          description: URL of the article's copy on Naver News.
        is_video:
          type: boolean
          description: Whether the article is a video clip.
        is_press_pick:
          type: boolean
          description: Whether the outlet chose the article as one of its picks on Naver News.
        related_news:
          type: array
          items:
            "$ref": "#/components/schemas/RelatedNews"
        related_news_count:
          type: integer
          description: Number of related articles Naver groups with this one.
        related_news_link:
          type: string
          description: Naver News URL listing every related article.
    RelatedNews:
      type: object
      required:
      - title
      - link
      - source
      - date
      properties:
        title:
          type: string
          description: Headline of the related article.
        link:
          type: string
          description: URL of the related article on the outlet's website.
        source:
          type: string
          description: Name of the outlet that published the related article.
        press_id:
          type: string
          description: Naver press code of the outlet, accepted by the press_id parameter.
        date:
          type: string
          description: Publication date of the related article as Naver shows it.
        naver_news_link:
          type: string
          description: URL of the related article's copy on Naver News.
        is_press_pick:
          type: boolean
          description: Whether the outlet chose the related article as one of its picks on Naver News.
    Pagination:
      type: object
      required:
      - current_page
      properties:
        current_page:
          type: integer
          description: Current page number, starting at 1.
        next_page:
          type: integer
          description: Number of the next page, to pass as the page parameter.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
