US Precipitation by Date Range Service

How to Use the US Precipitation Date Range API

The US Precipitation Date Range API by GeoRiskServices allows users to retrieve precipitation data for a specified date range at a given location. This API is ideal for weather analysis, agricultural planning, and environmental studies.

API Endpoint

The API can be accessed via the following endpoint:

https://www.allthingsdev.co/apimarketplace/endpoints/geo-risk-services/67b9249d563cbd684a8bf1fc

JSON Schema Overview

Required Parameters

The API requires the following input:

Latitude and Longitude:
- lat: Latitude (number, between -90 and 90).
- lon: Longitude (number, between -180 and 180).
- Or
- address: single line format
Date Range:
- start_date: Start date in YYYY-MM-DD format.
- end_date: End date in YYYY-MM-DD format.

Optional Parameters

units: String – Unit for precipitation measurement ("i" or "m"). Default: "f"
perf: Boolean – return database & api performance in ms
anno: Boolean – return api annotations

Example Schemas

The api will accept address or combination of latitude & longitude.

{
  "lat": 34.052235,
  "lon": -118.243683,
  "perf" : true,
  "anno" : true,
  "units" : "i",
  "start_date" : "2024-01-01",
  "end_date" : "2024-02-01"
}

{
    "address": "235 2nd St, San Francisco, CA 94105",
    "perf" : true,
    "anno" : true,
    "units" : "i",
    "start_date" : "2024-01-01",
    "end_date" : "2024-02-01"
}

Step-by-Step Guide to Using the API

Step 1: Prepare Your Request

Choose the geographic coordinates (lat, lon) and specify the date range (start_date, end_date).

Step 2: Send a POST Request

Send a POST request to the API endpoint with the JSON payload.

Example Request with Lat/Lon:

curl --location 'https://Geo-Risk-Services.proxy-production.allthingsdev.co/usprecipdaterange' \
--header 'Content-Type: application/json' \
--header 'x-apihub-key: fj1jXaBtgygVVeOXYx6F1mNcd70F00XmnLnbEvGnNr831j-t5f' \
--header 'x-apihub-host: Geo-Risk-Services.allthingsdev.co' \
--header 'x-apihub-endpoint: fe7209ba-65cd-4bb6-8f57-20f8b0fd0ff2' \
--header 'Content-Type: application/json' \
--data '{
  "lat": 34.052235,
  "lon": -118.243683,
  "perf" : true,
  "anno" : true,
  "units" : "i",
  "start_date" : "2024-01-01",
  "end_date" : "2024-02-01"
}'

Example Request:

curl --location 'https://Geo-Risk-Services.proxy-production.allthingsdev.co/usprecipdaterange' \
--header 'Content-Type: application/json' \
--header 'x-apihub-key: fj1jXaBtgygVVeOXYx6F1mNcd70F00XmnLnbEvGnNr831j-t5f' \
--header 'x-apihub-host: Geo-Risk-Services.allthingsdev.co' \
--header 'x-apihub-endpoint: fe7209ba-65cd-4bb6-8f57-20f8b0fd0ff2' \
--header 'Content-Type: application/json' \
--data '{
	"address": "235 2nd St, San Francisco, CA 94105",
	"perf" : true,
    "anno" : true,
    "units" : "i",
    "start_date" : "2024-01-01",
    "end_date" : "2024-02-01"
}'

Step 3: Interpret the Response

The API responds with precipitation data for the specified date range.

Example Response:

{
    "status": "success",
    "db_perf_ms": 53,
    "api_perf_ms": 310,
    "error": "",
    "max_precip_dt": "2024-12-03",
    "input_params": {
        "lat": 37.786045080006,
        "lon": -122.397232161538,
        "address": "235 2nd St, San Francisco, CA 94105",
        "perf": true,
        "anno": true,
        "units": "i",
        "start_dt": "2024-01-01",
        "end_dt": "2024-02-01"
    },
    "results": [
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-01"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-02"
        },
        {
            "units": "in",
            "precip": 0.65,
            "precip_date": "2024-01-03"
        },
        {
            "units": "in",
            "precip": 0.17,
            "precip_date": "2024-01-04"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-05"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-06"
        },
        {
            "units": "in",
            "precip": 0.12,
            "precip_date": "2024-01-07"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-08"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-09"
        },
        {
            "units": "in",
            "precip": 0.18,
            "precip_date": "2024-01-10"
        },
        {
            "units": "in",
            "precip": 0.11,
            "precip_date": "2024-01-11"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-12"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-13"
        },
        {
            "units": "in",
            "precip": 1.29,
            "precip_date": "2024-01-14"
        },
        {
            "units": "in",
            "precip": 0.09,
            "precip_date": "2024-01-15"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-16"
        },
        {
            "units": "in",
            "precip": 0.75,
            "precip_date": "2024-01-17"
        },
        {
            "units": "in",
            "precip": 0.01,
            "precip_date": "2024-01-18"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-19"
        },
        {
            "units": "in",
            "precip": 0.48,
            "precip_date": "2024-01-20"
        },
        {
            "units": "in",
            "precip": 0.53,
            "precip_date": "2024-01-21"
        },
        {
            "units": "in",
            "precip": 0.98,
            "precip_date": "2024-01-22"
        },
        {
            "units": "in",
            "precip": 0.88,
            "precip_date": "2024-01-23"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-24"
        },
        {
            "units": "in",
            "precip": 0.37,
            "precip_date": "2024-01-25"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-26"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-27"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-28"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-29"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-30"
        },
        {
            "units": "in",
            "precip": 0,
            "precip_date": "2024-01-31"
        },
        {
            "units": "in",
            "precip": 1.11,
            "precip_date": "2024-02-01"
        }
    ],
    "annotations": [
        {
            "org": "US Census",
            "org_link": "https://www.census.gov/",
            "data_service": "https://geocoding.geo.census.gov/geocoder/",
            "grs_last_udpate": "2024-08-17T22:22:32.631807+00:00"
        },
        {
            "org": "US NCEI - NOAA",
            "org_link": "https://www.ncei.noaa.gov/",
            "data_service": "https://console.cloud.google.com/storage/browser/noaa-ncei-nclimgrid-daily/cog/2024;tab=objects?pageState=(%22StorageObjectListTable%22:(%22f%22:%22%255B%255D%22))&prefix=&forceOnObjectsSortingFiltering=false&invt=AbjC2w&inv=1",
            "grs_last_udpate": null
        },
        {
            "org": "USGS",
            "org_link": "https://www.usgs.gov",
            "data_service": "https://apps.nationalmap.gov/epqs/",
            "grs_last_udpate": "2024-09-01T01:25:43.77738+00:00"
        }
    ]
}

unit: Measurement unit (e.g., f, c).
date_range: Start and end dates of the requested period.

Use Cases

Agricultural Planning: Estimate precipitation levels for crop planning.
Environmental Research: Analyze precipitation trends over a period.
Urban Planning: Assess rainfall impacts on infrastructure.

Tips for Efficient Use

Ensure the date range is valid and within historical data limits.
Use appropriate units ("i" or "m") depending on your analysis needs.
Combine precipitation data with other GeoRiskServices APIs for comprehensive geospatial risk assessments.

The US Precipitation Date Range API is a versatile tool for weather-related, agricultural, and risk insights and decision-making.

Geo Risk Services