Only this pageAll pages
Powered by GitBook
1 of 6

Nubila API Documentation

Loading...

Loading...

Loading...

Loading...

Loading...

Loading...

Appendix - Terms of Use of Nubila Premium Weather API

Last Updated: June 17, 2025

These Terms of Use (“Terms”) govern your use of the Nubila Premium Weather Data API (“API”), made available by ButterflyX Inc. (“Nubila”, “we”, or “us”). These Terms are binding upon all users granted access to the API under any agreement or memorandum, including but not limited to evaluation agreements or credit-based access. If you do not agree to these Terms, you may not access or use the API.

1. Eligibility and Scope

These Terms apply exclusively to API users who:

  • Have entered into a separate agreement or MOU with Nubila granting API access (the “Access Agreement”);

  • Have received API credentials (e.g., keys or tokens) directly from Nubila;

  • Are using the API solely for internal evaluation, development, or testing purposes, unless otherwise authorized in writing.

2. License Grant

Subject to these Terms and the Access Agreement, Nubila grants you a non-exclusive, non-transferable, non-sublicensable, revocable license to access and use the API solely:

  • For internal development, prototyping, and testing purposes;

  • Within the scope and duration specified in the Access Agreement;

  • In compliance with all applicable laws and Nubila documentation.

You must use the API in accordance with Nubila’s published documentation (the “Documentation”), available at .

The Documentation is for technical reference only and does not override any part of this Terms of Use.

3. Usage Restrictions

You agree not to, and shall not permit others to:

  • Use the API or any data derived from it in any commercial, production, or client-facing applications without explicit written consent from Nubila;

  • Resell, repackage, redistribute, relicense, or otherwise make available the API or its output to any third party;

  • Use the API in any way that could harm or degrade the performance or integrity of Nubila’s systems;

  • Reverse engineer, decompile, or otherwise attempt to derive source code, algorithms, or database structure from the API;

4. Rate Limits and Quotas

  • Nubila may impose rate limits, call quotas, or bandwidth caps on API usage;

  • Any such limits will be documented in Nubila’s technical documentation or communicated directly;

  • Sustained violation of these limits may result in throttling or suspension of access.

5. Attribution and Marketing

If your agreement with Nubila includes optional marketing deliverables (e.g., Medium articles, tweets, Spaces), the following conditions apply:

  • All public references to Nubila must include proper attribution and links to Nubila’s website or official social media;

  • Written approval from Nubila is required before any content mentioning the API or company is published;

  • You may not suggest that your use of the API constitutes an endorsement or partnership without express consent.

6. Ownership and Intellectual Property

  • The API, including all data, code, specifications, analytics, and documentation, is the exclusive property of Nubila;

  • No rights or licenses are granted except those expressly stated in these Terms;

  • All suggestions, feedback, or improvements provided to Nubila in the course of API use may be freely used by Nbilua for any purpose, without attribution or compensation.

7. Confidentiality

You agree to maintain in strict confidence any:

  • Non-public API documentation;

  • Access credentials (e.g., API keys, tokens);

  • Data received through the API not intended for public release.

You shall take all reasonable precautions to prevent unauthorized access, disclosure, or use. The confidentiality obligations set forth herein shall survive the termination or expiration of these Terms for a period of three (3) years.

8. Monitoring and Enforcement

Nubila reserves the right to:

  • Monitor your API usage to ensure compliance;

  • Audit your usage logs and internal use cases;

  • Suspend or revoke access at any time in the event of violation, abuse, or security risk.

9. Disclaimer of Warranties

The API is provided “as is” and “as available” without warranty of any kind, including but not limited to:

  • Accuracy, completeness, or timeliness of the data;

  • Performance, uptime, or error-free operation;

  • Fitness for a particular purpose.

10. Limitation of Liability

To the maximum extent permitted by law:

  • Nubila shall not be liable for any indirect, incidental, punitive, or consequential damages; even if Nubila has been advised of the possibility of such damages.

  • Nubila’s total aggregate liability arising from or related to API use shall not exceed the equivalent USD value of the $NUBI credits allocated under the Access Agreement.

11. Termination

Your access to the API may be terminated:

  • Upon expiration of the trial or evaluation period;

  • Immediately upon breach of these Terms or applicable agreements;

  • At Nubila’s sole discretion with or without cause, upon written notice.

Upon termination, you must cease all use of the API and delete any stored data obtained through it. The termination of these Terms shall not affect any rights or obligations of either Party that have accrued prior to the effective date of termination.

12. Governing Law and Dispute Resolution

These Terms shall be governed by the laws of the State of California, without regard to conflict of law principles. Any disputes arising under or related to these Terms shall be resolved exclusively in the courts of San Francisco County, California.

13. Changes to Terms

Nubila may update these Terms at any time. Notifications of changes may be provided via email or through your point of contact.

Updates to the API Documentation do not constitute changes to these Terms.

14. Contact

For support or legal inquiries:

Email: data@nubila.ai Docs:X:

Use the API in any manner that infringes on intellectual property, privacy, or contractual rights of third parties;

  • Access or use the API in connection with any product or service that competes with Nubila.

  • https://nubila-1.gitbook.io/api-docs
    https://nubila-1.gitbook.io/api-docs
    @nubilanetwork

    Forecast API

    Introduction

    The endpoint provides the user the ability to check the forecast of a location based on geographical coordinates.

    Authentication

    Authentication is achieved by passing a custom header named X-Api-Key containing the API key.

    Endpoint

    https://api.nubila.ai/api/v1/forecast

    Parameters

    Parameter
    Required
    Type
    Description
    Example

    Example Request

    Example Response (success)

    Example response (error)

    Response Fields description

    Root Fields

    • ok (boolean): Indicates whether the request was successful.

    • message (string): In case of unsuccessful request, a message explaining why the request failed

    data objects’ fields

    Metadata

    • id (string): Unique identifier for the weather data record.

    • created_at (string, ISO 8601): Timestamp when the record was created.

    • updated_at

    Location Information

    • latitude (number): Latitude of the location.

    • longitude (number): Longitude of the location.

    • location_name (

    Weather Conditions

    • temperature (number): Current temperature in degrees Celsius.

    • temperature_min (number): Minimum recorded temperature in degrees Celsius.

    • temperature_max

    Wind Data

    • wind_speed (number): Wind speed in meters per second.

    • wind_direction (number): Wind direction in degrees (0-360, where 0 represents north).

    Weather Condition Details

    • condition (string): General weather condition (e.g., “Clouds”, “Rain”).

    • condition_desc (string): Detailed weather description (e.g., “overcast clouds”).

    Time & Source Information

    • timestamp (number): Unix timestamp (seconds since epoch) representing the time for which the weather is predicted.

    • timezone (number): Timezone offset in seconds from UTC.

    Overview

    Nubila API provides a comprehensive set of endpoints for accessing weather data, enabling developers to easily retrieve weather information for specific geographical locations. The API offers two primary modes of data retrieval:

    • Current Weather Data - Get real-time weather conditions for a specific location

    • Weather Forecast Data - Access weather forecasts for a specific location

    Our API delivers detailed weather information, including key meteorological data such as temperature, humidity, wind speed, and atmospheric pressure, along with additional information like weather conditions, UV index, and more. All data is returned in a standardized JSON format for seamless integration into various applications.

    Why Nubila?

    What sets Nubila apart is our unique decentralized weather data collection network. Unlike traditional weather APIs that rely on sparse conventional weather stations, Nubila leverages tens of thousands of decentralized weather stations distributed worldwide. This extensive network enables us to:

    • Provide Hyperlocal Data - Access precise weather information for specific locations rather than interpolated regional data

    • Deliver Real-Time Updates - Get current conditions from actual on-site measurements

    • Ensure Higher Accuracy - Benefit from dense sensor coverage that captures microclimate variations

    • Cover More Locations - Access data from areas traditionally underserved by conventional weather stations

    Our decentralized approach to weather data collection results in more granular, accurate, and timely weather information compared to traditional meteorological services.

    Key Features

    • Simple Authentication - API Key-based authentication system

    • Standardized Format - All responses in structured JSON format

    • Precise Geolocation - Weather data based on exact latitude and longitude coordinates

    • Rich Weather Parameters - Comprehensive meteorological data points

    Service Plans

    We offer two service plans to meet different user needs:

    Free Plan

    • Basic weather data access

    • Standard API functionality

    • Basic technical support

    Premium Plan

    • Full weather data access

    • Priority technical support

    • Custom development support

    • Advanced features

    Note: Rate limits and usage restrictions on API calls may be implemented based on user requirements and service conditions. We recommend describing your intended use case and requirements during the application process so we can provide the most suitable solution.

    Getting Started

    To start using the Nubila API, follow these steps:

    1. Request Access

      • Choose your preferred service plan (Free/Premium)

      • Submit the apply form with your e-mail and use case on

      • Specify any customization requirements if needed

    The following sections of and provide detailed information about each API endpoint, including usage instructions and parameter specifications.

    Customization Support - Custom development services available based on specific requirements

    Obtain Credentials

    • Receive your unique API Key

    • Review documentation and best practices

  • Begin Integration

    • Prepare the latitude and longitude coordinates for your locations of interest

    • Choose the appropriate endpoint for your needs:

      • /api/v1/weather for current weather data

      • /api/v1/forecast for weather forecasts

  • our website
    Weather API
    Forecast API
    error_code
    (
    number
    ): System error code representing the error
  • data (array): Contains an array of objects, representing forecast for a given timestamp, at hourly intervals

  • (
    string
    , ISO 8601): Timestamp when the record was last updated.
  • tag (string): Custom tag (if applicable).

  • string
    ): Name of the location.
  • sea_level (number): Elevation of the location in meters.

  • (
    number
    ): Maximum recorded temperature in degrees Celsius.
  • feels_like (number): Perceived temperature in degrees Celsius (considering wind and humidity).

  • pressure (number): Atmospheric pressure in hPa (hectopascals).

  • humidity (number): Humidity percentage.

  • uv (number): Ultraviolet (UV) index.

  • luminance (number): Luminance level (exact unit depends on the source).

  • rain (number): Precipitation level in millimeters.

  • wet_bulb (number): Wet-bulb temperature in degrees Celsius (a measure of temperature considering humidity).

  • condition_code
    (
    number
    ): Numeric code representing the weather condition.
  • condition_icon (string): Icon identifier for the weather condition.

  • lat

    Yes

    number

    Latitude value for the requested area

    37.2144

    lon

    Yes

    number

    Longitude value for the requested area

    -121.8574

    curl -X GET \
    --location "https://api.nubila.ai/api/v1/forecast?lat=37.2144&lon=-121.8574" \
    -H "X-Api-Key: 26...4e"
    curl -X GET --location "https://api.nubila.ai/api/v1/forecast?lat=37.2144&lon=-121.8574" \
        -H "X-Api-Key: 26...4e"
    {
        "data": [
            {
                "id": "0",
                "created_at": "0001-01-01T00:00:00Z",
                "updated_at": "0001-01-01T00:00:00Z",
                "latitude": 37.2144,
                "longitude": -121.8574,
                "temperature": 11.54,
                "temperature_min": 11.2,
                "temperature_max": 11.54,
                "feels_like": 10.55,
                "pressure": 1011,
                "humidity": 69,
                "wind_speed": 2.22,
                "wind_direction": 0,
                "condition": "Clouds",
                "condition_desc": "broken clouds",
                "condition_code": 803,
                "condition_icon": "04d",
                "uv": 0,
                "luminance": 0,
                "sea_level": 1011,
                "rain": 0,
                "wet_bulb": 0,
                "timestamp": 1739394000,
                "timezone": -28800,
                "location_name": "Cambrian Park, US",
                "source": "o",
                "tag": ""
            },
            {
                "id": "0",
                "created_at": "0001-01-01T00:00:00Z",
                "updated_at": "0001-01-01T00:00:00Z",
                "latitude": 37.2144,
                "longitude": -121.8574,
                "temperature": 11.24,
                "temperature_min": 10.65,
                "temperature_max": 11.24,
                "feels_like": 10.3,
                "pressure": 1011,
                "humidity": 72,
                "wind_speed": 2.24,
                "wind_direction": 0,
                "condition": "Clouds",
                "condition_desc": "broken clouds",
                "condition_code": 803,
                "condition_icon": "04d",
                "uv": 0,
                "luminance": 0,
                "sea_level": 1011,
                "rain": 0,
                "wet_bulb": 0,
                "timestamp": 1739404800,
                "timezone": -28800,
                "location_name": "Cambrian Park, US",
                "tag": ""
            }
        ],
        "ok": true
    }
    {
        "ok": false,
        "message": "Invalid longitude",
        "error_code": 40000
    }

    Use Cases

    Nubila API delivers hyperlocal, real-time weather data to power smarter decision-making across a wide range of industries and applications. Below are eight key sectors where Nubila’s weather intelligence creates tangible value, each with some practical examples. These examples highlight key sectors, but the capabilities of the Nubila API extend far beyond—limited only by your imagination and implementation needs.


    🌾 Agriculture — Optimize Farming Decisions

    Enable climate-resilient farming using hyperlocal, real-time weather data.

    Weather API

    Introduction

    The endpoint provides the user the ability to check the current weather based on geographical coordinates.

    Authentication

    Authentication is achieved by passing a custom header named

    Nubila API Documentation

    Welcome to explore Nubila API

    Nubila API is a next-generation weather data service that revolutionizes how developers access meteorological information. Built on a unique decentralized network of tens of thousands of weather stations worldwide, Nubila delivers hyperlocal, real-time weather data with unprecedented accuracy and coverage.

    Unlike traditional weather services that rely on sparse conventional stations, our distributed sensor network captures precise microclimate variations, providing you with actual on-site measurements rather than interpolated regional estimates. Whether you need current conditions or detailed forecasts, Nubila API offers comprehensive weather intelligence through simple, standardized endpoints.

    What makes Nubila different:

    Smart Irrigation Control

    Adjust irrigation systems dynamically based on live humidity, rainfall, and evaporation data to reduce water waste.

  • Crop Disease Forecasting

    Use humidity, temperature, and wet bulb readings to predict fungal disease outbreaks and take preventive actions.

  • Machinery Scheduling Optimization

    Schedule planting or fertilization based on wind and rain forecasts to avoid downtime or crop damage.


  • 🏦 Finance & Insurance — Weather-Aware Risk Models

    Enhance risk prediction and pricing accuracy in financial services.

    • Agri-Insurance Risk Scoring

      Leverage historical drought and rainfall patterns to assess risk for different cultivation zones.

    • Weather Derivatives Modeling

      Feed temperature data into HDD/CDD models for weather-linked contracts and financial instruments.

    • Auto-Triggered Claims Processing

      Use real-time wind or rainfall data to automatically initiate claim workflows after verified extreme weather events.


    🏘️ Consumer & Smart Living — Enable Weather-Aware Devices

    Improve daily convenience, safety, and home automation through contextual weather data.

    • Automated Curtain and Skylight Control

      Close shades when UV is high or rain is approaching, using live weather updates.

    • Personalized Outfit & Travel Suggestions

      Recommend attire or remind users to bring umbrellas based on local temperature and forecast.

    • Elderly & Child Care Alerts

      Notify caregivers when strong winds or large temperature swings make outdoor activities risky.


    🏃‍♀️ Sports & Outdoor — Keep Activities Safe & Efficient

    Protect participants and enhance experience in recreational and competitive outdoor activities.

    • Optimal Exercise Time Suggestion

      Recommend ideal training windows based on weather conditions such as wind and UV index.

    • Event Day Monitoring

      Adapt race logistics (e.g., for marathons) using real-time heat, humidity, and storm alerts.

    • Extreme Weather Contingency Plans

      Automatically monitor conditions and notify organizers if thresholds for postponement or cancellation are met.


    ✈️ Travel & Transportation — Plan Ahead with Confidence

    Make smarter routing and planning decisions for both personal and commercial travel.

    • Flight Risk Assessment

      Predict delays using real-time wind, pressure, and storm condition inputs at departure and arrival points.

    • Smart Road Trip Planner

      Adapt travel routes based on up-to-the-hour precipitation, fog, or storm forecasts.

    • Tourist Experience Optimizer

      Suggest outdoor vs indoor activities based on forecasted sunshine, wind, or rain for better visitor satisfaction.


    🏭 Industry & Warehousing — Ensure Operational Stability

    Maintain control over sensitive environments and prevent disruptions across industrial sites.

    • Climate-Sensitive Goods Monitoring

      Track real-time temperature and humidity in warehouses to protect pharmaceuticals, perishables, or electronics.

    • Wind Turbine Maintenance Scheduling

      Use forecasted wind speed and direction data to plan safe and efficient turbine inspections or servicing.

    • Chemical Plant Safety Automation

      Automatically trigger safety measures if rain or wind thresholds are exceeded near hazardous storage areas.


    🚚 Logistics & Delivery — Weather-Driven Logistics

    Minimize disruption and improve customer experience across delivery networks.

    • Cold Chain Transport Monitoring

      Ensure temperature-sensitive goods remain within safe ranges during transit using external weather feeds.

    • Last-Mile Dispatch Optimization

      Adjust delivery routes and ETAs based on real-time weather alerts like thunderstorms or heat waves.

    • Preemptive Rescheduling

      Use forecast insights to plan for rerouting or pre-delivery communication ahead of adverse conditions.


    🏙️ Public Sector & Urban Management — Smart City Enablement

    Empower cities to respond to changing environmental conditions with precision.

    • Urban Flood Mitigation

      Forecast intense rainfall and activate stormwater pumps or issue public alerts before critical thresholds are crossed.

    • Heat Island Detection & Cooling Strategy

      Identify and monitor urban heat pockets to plan interventions like tree planting or misting systems.

    • Emergency Broadcast Integration

      Push localized storm, wind, or heat warnings through integrated public communication channels.

    Hyperlocal precision - Get weather data for exact coordinates, not approximated regions

  • Real-time accuracy - Access live measurements from our extensive sensor network

  • Global coverage - Reach locations traditionally underserved by conventional weather stations

  • Developer-friendly - Simple API key authentication with structured JSON responses

  • Ready to integrate superior weather data into your applications? Let's get started.

    X-Api-Key
    containing the API key.

    Endpoint

    https://api.nubila.ai/api/v1/weather

    Parameters

    Parameter
    Required
    Description
    Example

    lat

    Yes

    Latitude value for the requested area

    37.2144

    lon

    Yes

    Longitude value for the requested area

    -121.8574

    Example Request

    Example Response (success)

    Example response (error)

    Response Fields description

    Root Fields

    • ok (boolean): Indicates whether the request was successful. true indiciates successful request

    • message (string): In case of unsuccessful request, a message explaining why the request failed

    • error_code (number): System error code representing the error

    • data (object): Contains the weather information object

    Metadata

    • id (string): Unique identifier for the weather data record.

    • created_at (string, ISO 8601): Timestamp when the record was created.

    • updated_at (string, ISO 8601): Timestamp when the record was last updated.

    Location Information

    • latitude (number): Latitude of the location.

    • longitude (number): Longitude of the location.

    • location_name (string): Name of the location.

    • address (string): Address of the location (if available).

    • elevation (number): Elevation of the location in meters.

    Weather Conditions

    • temperature (number): Current temperature in degrees Celsius.

    • temperature_min (number): Minimum recorded temperature in degrees Celsius.

    • temperature_max (number): Maximum recorded temperature in degrees Celsius.

    • feels_like (number): Perceived temperature in degrees Celsius (considering wind and humidity).

    • pressure (number): Atmospheric pressure in hPa (hectopascals).

    • humidity (number): Humidity percentage.

    • uv (number): Ultraviolet (UV) index.

    • luminance (number): Luminance level (exact unit depends on the source).

    • rain (number): Precipitation level in millimeters.

    • wet_bulb (number): Wet-bulb temperature in degrees Celsius (a measure of temperature considering humidity).

    Wind Data

    • wind_speed (number): Wind speed in meters per second.

    • wind_scale (number): Wind scale (e.g., Beaufort scale).

    • wind_speed_list (array|null): List of wind speed values over time (if available).

    • wind_scale_list (array|null): List of wind scale values over time (if available).

    • wind_direction (number): Wind direction in degrees (0-360, where 0 represents north).

    Weather Condition Details

    • condition (string): General weather condition (e.g., “Clouds”, “Rain”).

    • condition_desc (string): Detailed weather description (e.g., “overcast clouds”).

    • condition_code (number): Numeric code representing the weather condition.

    • condition_icon (string): Icon identifier for the weather condition.

    Time & Source Information

    • timestamp (number): Unix timestamp (seconds since epoch) representing the data retrieval time.

    • timezone (number): Timezone offset in seconds from UTC.

    System Status

    • tag (string): Custom tag (if applicable).

    • is_online (boolean): Indicates whether the weather station or source is online.

    • is_malfunction (boolean): Indicates whether there is a malfunction in the data source.

    curl -X GET \
    --location "https://api.nubila.ai/api/v1/weather?lat=37.2144&lon=-121.8574" \
    -H "X-Api-Key: 13...5c"
    curl -X GET --location "https://api.nubila.ai/api/v1/weather?lat=37.2144&lon=-121.8574" \
        -H "X-Api-Key: 13...5c"
    {
        "id": "0",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "latitude": 37.2144,
        "longitude": -121.8574,
        "temperature": 9.7,
        "temperature_min": 8.16,
        "temperature_max": 10.66,
        "feels_like": 7.36,
        "pressure": 1016,
        "humidity": 61,
        "wind_speed": 4.63,
        "wind_scale": 0,
        "wind_speed_list": null,
        "wind_scale_list": null,
        "wind_direction": 0,
        "condition": "Clouds",
        "condition_desc": "overcast clouds",
        "condition_code": 804,
        "condition_icon": "04n",
        "uv": 0,
        "luminance": 0,
        "elevation": 1016,
        "rain": 0,
        "wet_bulb": 0,
        "timestamp": 1739325314,
        "timezone": -28800,
        "location_name": "Cambrian Park",
        "address": "",
        "tag": "",
        "is_online": false,
        "is_malfunction": false
    }
    {
        "ok": false,
        "message": "Invalid longitude",
        "error_code": 40000
    }