Skip to main content

CIMIS API Data Source

The CIMIS API connector enables you to ingest reference evapotranspiration (ETo) and weather data from California's statewide network of over 150 automated weather stations, as well as spatial ETo and solar radiation data across the state. Follow the instructions below to create a new data flow that ingests data from a CIMIS API source in Nexla.
cimis_api.png

CIMIS API

Create a New Data Flow​

  1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

  2. Select the CIMIS API connector tile from the list of available connectors. Then, select the credential that will be used to connect to the CIMIS API, and click Next; or, create a new CIMIS API credential for use in this flow.

  3. In Nexla, CIMIS API data sources can be created using pre-built endpoint templates, which expedite source setup for common CIMIS API endpoints. Each template is designed specifically for the corresponding CIMIS API endpoint, making data source setup easy and efficient.
    • To configure this source using a template, follow the instructions in Configure Using a Template.

    CIMIS API sources can also be configured manually, allowing you to ingest data from CIMIS API endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common CIMIS API endpoints. Each template is designed specifically for the corresponding CIMIS API endpoint, making data source setup easy and efficient.

Endpoint Settings​

  • Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

    Get Data

    This endpoint retrieves evapotranspiration (ETo) and weather data from one or more CIMIS stations or zip code targets for a specified date range. Use it to ingest daily or hourly climate and irrigation reference data for agricultural planning, water management, or environmental reporting.

    • Sends a GET request to https://et.water.ca.gov/api/data. Required query parameters include targets (comma-separated station numbers or zip codes), startDate, and endDate (both in yyyy-MM-dd format).
    • Response data is extracted from $.data[*]. Each record represents a set of weather observations for one target and one time period. Use date/time macros for startDate and endDate to automate rolling date window ingestion.

    The appKey parameter is managed automatically by the CIMIS API credential. The optional dataItems parameter lets you request specific data fields (e.g., day-asce-eto,day-precip,day-air-tmp-max) to reduce response size.

    List Stations

    This endpoint returns a list of all CIMIS weather stations with their metadata and geographic locations. Use it to enumerate available stations, identify station numbers for use in data requests, or build a reference dataset of California weather monitoring locations.

    • Sends a GET request to https://et.water.ca.gov/api/station. No additional query parameters are required.
    • Response data is extracted from $.stations[*]. Each record contains station number, name, county, elevation, latitude, longitude, and active/inactive status.

    This endpoint returns both active and inactive stations. Filter on the IsActive field in your Nexla transform if you only want currently operating stations.

    List Spatial Zipcodes

    This endpoint returns spatial zipcode data representing CIMIS weather station coverage areas across California. Use it to map zip codes to spatial ET zones or to identify which zip codes are covered by CIMIS spatial data.

    • Sends a GET request to https://et.water.ca.gov/api/spatialzipcode. No additional query parameters are required.
    • Response data is extracted from $.spatialZipcodes[*]. Each record represents a zip code and its associated spatial coverage information.

    Spatial zipcode data is used for zip-code-based ETo requests that derive values from interpolated spatial data rather than a specific physical station.

    List Station Zipcodes

    This endpoint returns the mapping between CIMIS weather stations and their associated zip codes. Use it to determine which zip codes are served by which stations, or to build lookup tables for geographic data enrichment.

    • Sends a GET request to https://et.water.ca.gov/api/stationzipcode. No additional query parameters are required.
    • Response data is extracted from $.stationZipcodes[*]. Each record contains a station number and its associated zip code.

    This endpoint is useful as a reference dataset when you need to correlate station-based observations with zip-code-level geographic data.

Endpoint Testing​

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually​

CIMIS API sources can also be manually configured to ingest data from any valid CIMIS Web API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom query parameters.

API Method​

  1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

  2. Select the method that will be used for calls to the CIMIS API from the Method pulldown menu. The CIMIS Web API uses GET for all data retrieval requests.

API Endpoint URL​

  1. Enter the URL of the CIMIS API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and all required query parameters.

    The primary CIMIS Web API base URL is https://et.water.ca.gov/api/data. Common endpoint patterns include:

    • Daily station data: https://et.water.ca.gov/api/data?appKey=YOUR_APP_KEY&targets=2,8&startDate=2024-01-01&endDate=2024-01-31&dataItems=day-asce-eto,day-precip,day-sol-rad-avg
    • Hourly station data: https://et.water.ca.gov/api/data?appKey=YOUR_APP_KEY&targets=2&startDate=2024-01-01&endDate=2024-01-02&unitOfMeasure=H&dataItems=hly-asce-eto,hly-air-tmp
    • Zip code data: https://et.water.ca.gov/api/data?appKey=YOUR_APP_KEY&targets=95616&startDate=2024-01-01&endDate=2024-01-31

    The appKey query parameter is required for all data requests. Your AppKey is automatically included when using a configured CIMIS API credential. The targets parameter accepts one or more CIMIS weather station numbers (e.g., 2,8,127) or California zip codes (e.g., 95616). For a list of active stations and their numbers, visit the CIMIS station map.

    Key query parameters for the CIMIS data endpoint include:

    • targets (required): Comma-separated list of CIMIS station numbers or zip codes from which to retrieve data.
    • startDate (required): The start date of the data range in yyyy-MM-dd format.
    • endDate (required): The end date of the data range in yyyy-MM-dd format.
    • dataItems (optional): Comma-separated list of specific data items to include in the response (e.g., day-asce-eto, day-precip, day-air-tmp-max). When omitted, all available default items are returned.
    • unitOfMeasure (optional): Set to E for English units (default) or M for metric units. Use H in place of a date range unit when requesting hourly data.
    • priorityCodes (optional): Filter results by data priority codes.

Date/Time Macros (API URL)​

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements. This is especially useful for CIMIS data ingestion, where you typically want to retrieve data for a rolling date window (for example, the most recent day or the past week of weather station readings).

Date/time macros are particularly valuable for the CIMIS API because the startDate and endDate parameters require explicit date values. Using macros like {now-1} and {now} allows you to automatically retrieve the most recent available data on each ingestion run without manually updating the URL.

  1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

    • {now} – The current datetime
    • {now-1} – The datetime one time unit before the current datetime
    • {now+1} – The datetime one time unit after the current datetime
    • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-7) to indicate the datetime seven time units before the current datetime

    For example, to retrieve the previous day's data, you could set startDate={now-1}&endDate={now-1} in the URL. For a rolling 7-day window, use startDate={now-7}&endDate={now}.

  2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. For CIMIS API date parameters, select yyyy-MM-dd format, as this is the format required by the CIMIS API for startDate and endDate.

  3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)​

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when you need to dynamically specify CIMIS station numbers, zip codes, or date ranges based on values from other Nexla sources or lookups in your environment.

  1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

  2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data​

Optional

The CIMIS API returns data in a nested JSON structure. To configure Nexla to treat individual weather records as separate rows in the resulting Nexset, specify the path to the data array within the API response.

For example, the CIMIS data endpoint returns a response in this general structure:

{
  "Data": {
    "Providers": [
      {
        "Records": [
          { "Date": "...", "Julian": "...", "Station": "...", "Standard": "...", ... }
        ]
      }
    ]
  }
}

To access individual records, set the path to data to $.Data.Providers[*].Records[*].

Path to Data is essential for CIMIS API responses because they contain nested metadata. Without specifying the correct path, Nexla may treat the entire response as a single record rather than parsing the individual weather station data rows.

  • To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

    • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.Data.Providers[*].Records[*] to access individual records within the CIMIS response).
    Path to Data Example:

    For the CIMIS data endpoint, set the path to $.Data.Providers[*].Records[*] to treat each weather record as an individual row. You can also use $.Data.Providers[0].Records[*] when querying a single station.

Autogenerate Path Suggestions​

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

  • To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

  • Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

    PathSuggestions.png

Metadata​

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. This is useful when you want to preserve important contextual information that applies to all records but isn't part of the main data array.

For example, the CIMIS API response includes provider-level metadata such as the data owner and record type alongside the individual weather records. If you have specified the path to relevant records but want to preserve provider-level context, you can specify a path to this metadata to include it with each record.

Metadata paths are particularly useful for preserving API response context like station provider information, data type identifiers, or summary statistics that apply to all records in the CIMIS response.

  • To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

    • For responses in JSON format, enter the JSON path to the object or array that contains the metadata. For example, $.Data.Providers[0] to include provider-level metadata alongside each record.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). The CIMIS API supports responses in both JSON and XML formats. To explicitly request JSON, you can add Accept:application/json as a request header.

    You do not need to include any headers already present in the credentials. The AppKey authentication is handled via the URL query parameter and is managed automatically by Nexla based on your credential configuration.

Endpoint Testing​

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

  • To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

  • If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source​

  1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new CIMIS API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.