Public Holidays API in Java
Complete Java integration guide for the Public Holidays API. Copy the code below, add your RapidAPI key, and start building.
Prerequisites
- 1.Sign up for a free account on RapidAPI
- 2.Subscribe to the Public Holidays API (free tier available)
- 3.Copy your
X-RapidAPI-Keyfrom the dashboard
Complete Java Example
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class HelixApiExample {
public static void main(String[] args) throws Exception {
String url = "https://public-holidays-by-helix-api.p.rapidapi.com/holidays?country=US&year=2026";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("X-RapidAPI-Key", "YOUR_API_KEY")
.header("X-RapidAPI-Host", "public-holidays-by-helix-api.p.rapidapi.com")
.GET()
.build();
HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString()
);
System.out.println("Status: " + response.statusCode());
System.out.println("Body: " + response.body());
}
}Response Format
All Helix-API endpoints return a consistent JSON envelope:
{
"status": "ok",
"data": { ... },
"meta": {
"request_id": "req_abc123",
"latency_ms": 42
}
}On errors, status becomes "error" and a message field explains what went wrong.
Error Handling
| Status | Meaning | Action |
|---|---|---|
200 | Success | Parse the response body normally |
400 | Bad request | Check your request parameters |
401 | Unauthorized | Verify your X-RapidAPI-Key header |
429 | Rate limited | Wait and retry with exponential backoff |
500 | Server error | Retry after a short delay |
Java Best Practices
Java 11+ HttpClient
The example uses java.net.http.HttpClient, available since Java 11. No external libraries needed to call the Public Holidays API.
Spring RestTemplate / WebClient
In Spring Boot, use RestTemplate (blocking) or WebClient (reactive). Both handle serialization and error mapping.
Gson or Jackson for JSON
Parse the response body with Gson or Jackson to map it to a POJO. This gives you type safety and easy field access.
CompletableFuture for async
Use HttpClient.sendAsync() with CompletableFuture for non-blocking calls in high-throughput applications.
Public Holidays API Endpoints
/holidaysAll public holidays for a country and year
/nextUpcoming holidays for a country (next 365 days)
/countriesList all supported countries
Other Languages
View the Public Holidays API integration guide in another language: