节假日判断 API

通用错误码

以下错误码适用于平台全部 /v1/* 接口（各接口在「错误代码」Tab 中另有本接口补充说明）。

错误响应格式

HTTP 状态码非 2xx 时，响应体一般为：

{
  "error": {
    "code": "错误码",
    "message": "错误信息"
  }
}

错误码一览

HTTP	code	message	说明
400	invalid_params	参数无效	必填参数缺失、格式不合法或超出允许范围
404	not_found	资源不存在	按编码或 ID 查询时无匹配记录
429	rate_limit_exceeded	请求过于频繁	超过当前 IP 的访问频率限制
500	internal_error	服务器内部错误	服务端或数据库异常，请稍后重试

限流、缓存等 HTTP 响应头含义见上文「响应头说明」。

---

本接口补充

HTTP	code	message	说明
400	invalid_params	参数无效	日期格式错误、区间超限（>366 天）、end 早于 start、year 非法、农历年月日无效或闰月不存在

请求根地址为 https://www.resapi.cn。每个场景含 7 种语言（cURL → JavaScript → Python → Go → Java → PHP → C#）。

---

单日判断

GET /v1/holidays/check?date=2026-10-01

cURL

curl -s "https://www.resapi.cn/v1/holidays/check?date=2026-10-01" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/check?date=2026-10-01", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/check",
    params={"date": "2026-10-01"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

func main() {
	url := "https://www.resapi.cn/v1/holidays/check?date=2026-10-01"
	req, _ := http.NewRequest(http.MethodGet, url, nil)
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var out map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", out)
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String url = "https://www.resapi.cn/v1/holidays/check?date=2026-10-01";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Accept", "application/json")
            .GET()
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/check?date=2026-10-01";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/check?date=2026-10-01");
Console.WriteLine(json);

---

区间判断

GET /v1/holidays/range?start=2026-10-01&end=2026-10-08

cURL

curl -s "https://www.resapi.cn/v1/holidays/range?start=2026-10-01&end=2026-10-08" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/holidays/range");
url.searchParams.set("start", "2026-10-01");
url.searchParams.set("end", "2026-10-08");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/range",
    params={"start": "2026-10-01", "end": "2026-10-08"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/range?start=2026-10-01&end=2026-10-08"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/range?start=2026-10-01&end=2026-10-08";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/range?start=2026-10-01&end=2026-10-08";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/range?start=2026-10-01&end=2026-10-08");
Console.WriteLine(json);

---

下一个节假日（默认）

GET /v1/holidays/countdown?from=2026-06-02

cURL

curl -s "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/countdown",
    params={"from": "2026-06-02"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02");
Console.WriteLine(json);

---

剩余全部节假日倒计时

GET /v1/holidays/countdown?from=2026-06-02&all=1

cURL

curl -s "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/countdown",
    params={"from": "2026-06-02", "all": 1},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/countdown?from=2026-06-02&all=1");
Console.WriteLine(json);

---

公历转农历

GET /v1/holidays/solar-to-lunar?date=2026-06-03

cURL

curl -s "https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/solar-to-lunar",
    params={"date": "2026-06-03"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/solar-to-lunar?date=2026-06-03");
Console.WriteLine(json);

---

农历转公历

GET /v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18

cURL

curl -s "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18" \
  -H "Accept: application/json"

JavaScript

const res = await fetch(
  "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18",
  { headers: { Accept: "application/json" } },
);
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/lunar-to-solar",
    params={"lunar_year": 2026, "lunar_month": 4, "lunar_day": 18},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync(
    "https://www.resapi.cn/v1/holidays/lunar-to-solar?lunar_year=2026&lunar_month=4&lunar_day=18");
Console.WriteLine(json);

---

农历 / 节气 / 生肖 / 星座

GET /v1/holidays/lunar?date=2026-06-03

cURL

curl -s "https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/lunar",
    params={"date": "2026-06-03"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/lunar?date=2026-06-03");
Console.WriteLine(json);

---

年度二十四节气

GET /v1/holidays/terms?year=2026

cURL

curl -s "https://www.resapi.cn/v1/holidays/terms?year=2026" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/holidays/terms?year=2026", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/holidays/terms",
    params={"year": 2026},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/holidays/terms?year=2026"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/holidays/terms?year=2026";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/holidays/terms?year=2026";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

var json = await client.GetStringAsync("https://www.resapi.cn/v1/holidays/terms?year=2026");
Console.WriteLine(json);