OpenUV Getting Started: API Access and First Request (2026)

This guide outlines the process for developers to begin using the OpenUV API, focusing on initial setup and making a first successful API call. For a comprehensive overview of OpenUV's capabilities, refer to the OpenUV API documentation.

Getting started overview

Integrating OpenUV involves a series of steps to ensure proper access and usage:

1. Account Creation: Register for an account on the OpenUV website.
2. API Key Generation: Obtain your unique API key from your account dashboard.
3. First API Request: Construct and execute a basic API call using your key to retrieve UV index data.
4. Data Integration: Incorporate the retrieved data into your application logic.

Quick Reference: OpenUV Getting Started

The following table provides a summary of the initial steps:

Create an account and get keys

To begin using the OpenUV API, you must first create an account and obtain an API key. This key authenticates your requests and grants access to the data.

Account Registration

1. Navigate to the OpenUV homepage.
2. Look for a 'Sign Up' or 'Register' option, typically located in the top right corner.
3. Complete the registration form, providing necessary information such as email and password.
4. Verify your email address if prompted, which is a common security measure for API providers to confirm account ownership.

Upon successful registration, you will gain access to your personal OpenUV dashboard.

Obtaining Your API Key

Your API key is essential for authenticating requests to the OpenUV API. Without it, your requests will be rejected.

1. Log in to your newly created OpenUV account.
2. On your dashboard, locate a section labeled 'API Keys', 'My Keys', or similar.
3. Your unique API key will be displayed. Copy this key and store it securely. Treat your API key like a password; do not expose it in client-side code, public repositories, or unsecured environments.

OpenUV offers a free tier that includes 50 API calls per day. If your usage exceeds this limit, you may need to upgrade to a paid plan. Information on plan options is available on the OpenUV pricing page.

Your first request

Once you have your API key, you can make your first request to verify your setup and retrieve live UV data. The primary endpoint for current UV index information requires latitude and longitude coordinates.

API Endpoint Structure

The base URL for the OpenUV API is https://api.openuv.io/api/v1/. For current UV index data, you will typically use the /uv endpoint.

A typical request to get the current UV index will look like this, requiring lat (latitude), lng (longitude), and optionally alt (altitude in meters, defaults to 0) and dt (datetime in UTC, defaults to current time):

GET https://api.openuv.io/api/v1/uv?lat={latitude}&lng={longitude}

Authentication

OpenUV uses API key authentication, which means your API key needs to be included in the HTTP headers of your request. Specifically, you will use the x-access-token header.

Example Request with cURL

Using cURL is a common method for testing API endpoints directly from your terminal. Replace YOUR_API_KEY with your actual OpenUV API key and adjust the latitude and longitude as needed.

curl -X GET \
  'https://api.openuv.io/api/v1/uv?lat=34.0522&lng=-118.2437' \
  -H 'x-access-token: YOUR_API_KEY'

This example requests the current UV index for Los Angeles, California (latitude 34.0522, longitude -118.2437). To find latitude and longitude for a specific location, you can use a geocoding service like the Google Maps Geocoding API.

Understanding the Response

A successful request will return a JSON object containing various UV-related data points. The structure of the response typically includes:

• uv: The current UV index value.
• uv_max: The maximum UV index forecast for the day.
• uv_max_time: The UTC timestamp when the maximum UV index is expected.
• sun_info: Sunrise and sunset times.
• safe_exposure_time: Recommended safe exposure durations for different skin types.

Example JSON response:

{
      "result": {
        "uv": 3.5,
        "uv_max": 7.2,
        "uv_max_time": "2026-05-29T19:00:00.000Z",
        "ozone": 290.5,
        "ozone_time": "2026-05-29T12:00:00.000Z",
        "sun_info": {
          "sun_times": {
            "sunrise": "2026-05-29T10:45:00.000Z",
            "sunset": "2026-05-30T01:30:00.000Z"
          },
          "solar_noon": "2026-05-29T18:07:30.000Z",
          "solar_midnight": "2026-05-29T06:07:30.000Z"
        },
        "safe_exposure_time": {
          "st1": 300,
          "st2": 250,
          "st3": 200,
          "st4": 150,
          "st5": 100,
          "st6": 50
        }
      }
    }

For a detailed breakdown of all possible response fields, consult the OpenUV API reference documentation.

Common next steps

After successfully making your first OpenUV API call, consider these next steps for further integration and development:

1. Explore Additional Endpoints: Beyond current UV data, OpenUV offers forecasts and historical data. Review the API documentation to understand other available endpoints, such as:
   • /uv/forecast: Get UV index forecasts for a specific location.
   • /uv/estimated: Retrieve estimated UV index data for past dates.
2. Implement Error Handling: Your application should be prepared to handle various API responses, including error codes. Common HTTP status codes include 200 OK for success, 400 Bad Request for invalid parameters, 401 Unauthorized for missing or invalid API keys, and 429 Too Many Requests for exceeding rate limits. Understanding how to manage these responses is a fundamental aspect of robust web development.
3. Integrate into Your Application: Incorporate the API calls into your chosen programming language or framework. Many languages have HTTP client libraries (e.g., Python's requests, Node.js's axios, Java's HttpClient) that simplify making web requests and parsing JSON responses.
4. Monitor Usage: Keep track of your API call usage, especially if you are on the free tier or a plan with specific call limits. Your OpenUV dashboard typically provides usage statistics. This helps prevent unexpected service interruptions due to exceeding quotas.
5. Consider Caching: For frequently requested data or data that doesn't change rapidly, implement caching mechanisms to reduce the number of API calls and improve application performance. This is particularly relevant for UV forecasts which might not need to be fetched every minute.
6. Security Best Practices: Ensure your API key is never exposed on the client-side. For web applications, make API calls from your backend server. For mobile apps, consider using environment variables and secure storage for keys.
7. Explore SDKs (if available): While OpenUV primarily provides a REST API, some API providers offer Software Development Kits (SDKs) in various programming languages. SDKs can streamline integration by abstracting away the HTTP request details. Check the OpenUV documentation for any official or community-contributed SDKs that might simplify your development process.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for OpenUV:

• Invalid API Key (401 Unauthorized):
  • Check for typos: Ensure your x-access-token header value exactly matches the API key from your OpenUV dashboard. Copy-pasting is recommended.
  • Key placement: Verify the API key is in the x-access-token header, not in the URL or request body.
  • Account status: Confirm your OpenUV account is active and your key hasn't been revoked.
• Missing or Invalid Parameters (400 Bad Request):
  • Latitude and Longitude: Ensure lat and lng parameters are present in the URL and are valid numerical values within geographical ranges (latitude -90 to +90, longitude -180 to +180).
  • Parameter names: Double-check that parameter names match those specified in the OpenUV API documentation (e.g., lat, lng, not latitude, longitude).
• Rate Limit Exceeded (429 Too Many Requests):
  • Check usage: Refer to your OpenUV dashboard to see your current API call usage against your plan's limits.
  • Daily reset: Remember the free tier resets daily. Wait for the reset period or consider upgrading your plan if continuous higher usage is needed.
  • Caching: Implement client-side caching to reduce redundant requests, especially for data that doesn't change frequently.
• Network Issues:
  • Internet connection: Verify your machine has an active internet connection.
  • Firewall/Proxy: Corporate networks or local firewalls can sometimes block outgoing requests. Check your network configuration.
• Incorrect Endpoint:
  • Verify URL: Ensure the base URL and endpoint path (e.g., api.openuv.io/api/v1/uv) are correctly formed according to the OpenUV API reference.
  • HTTP method: Confirm you are using the correct HTTP method (e.g., GET for retrieving data).
• JSON Parsing Errors:
  • If the API returns a successful status code (200 OK) but your application struggles to parse the response, inspect the raw JSON output to ensure it's well-formed. Use online JSON validators if necessary.

If issues persist, consult the OpenUV API documentation for more specific error code explanations or visit their support resources.