Web Service Information

The U.S. Drought Monitor statistics are available through a set of REST services. The information below describes how to use these services. If you have any questions about the services, feel free to contact us.

Comprehensive Statistics


Comprehensive statistics include values for None and D0-D4 for each week for the selected area(s)

URL Structure

Use the following structure for the URL:

https://usdmdataservices.unl.edu/api/[area]/[statistics type]?aoi=[aoi]&startdate=[start date]&enddate=[end date]&statisticsType=[statistics type]

An explanation of each of the variables in the above URL is given below.

[area]

The following areas are available:

Area Type Value
National USStatistics
USDA Climate Hubs ClimateHubStatistics
Regional Drought Early Warning Systems (RDEWS) RegionalDroughtEarlyWarningSystemStatistics
Counties CountyStatistics
States StateStatistics
National Weather Service Weather Forecast Offices (WFOs) WeatherForecastOfficeStatistics
U.S. Army Corps of Engineers Districts USACEDistrictStatistics
U.S. Army Corps of Engineers Divisions USACEDivisionStatistics
U.S. Urban Areas UrbanAreaStatistics
River Forecast Centers RiverForecastCenterStatistics
Regional Climate Center Regions RegionStatistics
National Weather Service Regions NWSRegionStatistics
Hydrologic Units (HUCs) HUCStatistics
FEMA Regions FEMARegionStatistics
Climate Divisions ClimateDivisionStatistics

[statistics type]

Statistics Type Value
Area GetDroughtSeverityStatisticsByArea
Percent of Area GetDroughtSeverityStatisticsByAreaPercent
Population GetDroughtSeverityStatisticsByPopulation
Percent of Population GetDroughtSeverityStatisticsByPopulationPercent
DSCI GetDSCI

[aoi]

Select a specific area within the type of area (i.e. a single state or county).

National

  • Use us for both the continental U.S. and total U.S.
  • Use conus for the continental U.S. only
  • Use total for the total U.S.

USDA Climate Hubs

  • The climate hubs use an ID number
    • California = 1
    • Caribbean = 2
    • Midwest = 3
    • Northeast = 4
    • Northern Forests = 5
    • Northern Plains = 6
    • Northwest = 7
    • Southeast  = 8
    • Southern Plains = 9
    • Southwest = 10

Regional Drought Early Warning Systems (RDEWS)

  • Each RDEWS has been assigned an ID number
    • California-Nevada = 2
    • Intermountain West = 20
    • Midwest = 4
    • Missouri River Basin = 7
    • Northeast = 23
    • Pacific Northwest = 5
    • Southeast = 24
    • Southern Plains = 8

Counties

State

National Weather Service Weather Forecast Offices (WFOs)

U.S. Army Corps of Engineers Districts

U.S. Army Corps of Engineers Divisions

Urban Areas

  • Use the geo ID for each urban area

River Forecast Centers

  • Use the RFC code (i.e. CBRFC = Colorado Basin RFC)

Regional Climate Center Regions

  • The regions are identified by an ID number
    • High Plains = 1
    • Midwest = 2
    • Northeast = 3
    • South = 4
    • Southeast = 5
    • West = 6

National Weather Service Regions

Hydrologic Units (HUCs)

  • Use the HUC ID number (for 2, 4, 6 and 8 digit)

FEMA Regions

Climate Divisions

  • Use the climate division’s ID number

[start date] and [end date]

Use the following date format M/D/YYYY for the start date and end date

[statistics type]

Choose between traditional or categorical statistics. Use a value of 1 for traditional or 2 for categorical.

Output Format

By default the data are output in XML format. You can specify an output format in the ACCEPT request header. The format options are XML, CSV, and JSON.

Note: Using a web browser to retrieve the data will return the data in XML format by default.

Example

If a person wanted to obtain statistics for the total area in drought for both the continental U.S. and the total U.S. between the dates of January 1st, 2012 and January 1st, 2013 in traditional format, the URL would look like the following:

https://usdmdataservices.unl.edu/api/USStatistics/GetDroughtSeverityStatisticsByArea?aoi=us&startdate=1/1/2012&enddate=1/1/2013&statisticsType=1

Statistics by Threshold


A set of statistics can be obtained by minimum drought category and also minimum and maximum statistics values (i.e. 0 to 100 percent of area).

URL Structure

https://usdmdataservices.unl.edu/api/[area]/[statistics type]?aoi=[aoi]&dx=[drought level]&DxLevelThresholdFrom=[minimum threshold]&DxLevelThresholdTo=[maximum threshold]&startdate=[start date]&enddate=[end date]&statisticsType=[statistics format]

An explanation of each of the variables in the above URL is given below.

[area]

The following areas are available:

Area Type Value
National USStatistics
USDA Climate Hubs ClimateHubStatistics
Regional Drought Early Warning Systems (RDEWS) RegionalDroughtEarlyWarningSystemStatistics
Counties CountyStatistics
States StateStatistics
National Weather Service Weather Forecast Offices (WFOs) WeatherForecastOfficeStatistics
U.S. Army Corps of Engineers Districts USACEDistrictStatistics
U.S. Army Corps of Engineers Divisions USACEDivisionStatistics
U.S. Urban Areas UrbanAreaStatistics
River Forecast Centers RiverForecastCenterStatistics
Regional Climate Center Regions RegionStatistics
National Weather Service Regions NWSRegionStatistics
Hydrologic Units (HUCs) HUCStatistics
FEMA Regions FEMARegionStatistics
Climate Divisions ClimateDivisionStatistics

[statistics type]

Statistics Type Value
Area GetDroughtSeverityStatisticsByArea
Percent of Area GetDroughtSeverityStatisticsByAreaPercent
Population GetDroughtSeverityStatisticsByPopulation
Percent of Population GetDroughtSeverityStatisticsByPopulationPercent

[aoi]

Select a specific area within the type of area (i.e. a single state or county).

National

  • Use us for both the continental U.S. and total U.S.
  • Use conus for the continental U.S. only
  • Use total for the total U.S.

USDA Climate Hubs

  • The climate hubs use an ID number
    • California = 1
    • Caribbean = 2
    • Midwest = 3
    • Northeast = 4
    • Northern Forests = 5
    • Northern Plains = 6
    • Northwest = 7
    • Southeast  = 8
    • Southern Plains = 9
    • Southwest = 10

Regional Drought Early Warning Systems (RDEWS)

  • Each RDEWS has been assigned an ID number
    • California-Nevada = 2
    • Intermountain West = 20
    • Midwest = 4
    • Missouri River Basin = 7
    • Northeast = 23
    • Pacific Northwest = 5
    • Southeast = 24
    • Southern Plains = 8

Counties

State

National Weather Service Weather Forecast Offices (WFOs)

U.S. Army Corps of Engineers Districts

U.S. Army Corps of Engineers Divisions

Urban Areas

  • Use the geo ID for each urban area

River Forecast Centers

  • Use the RFC code (i.e. CBRFC = Colorado Basin RFC)

Regional Climate Center Regions

  • The regions are identified by an ID number
    • High Plains = 1
    • Midwest = 2
    • Northeast = 3
    • South = 4
    • Southeast = 5
    • West = 6

National Weather Service Regions

Hydrologic Units (HUCs)

  • Use the HUC ID number (for 2, 4, 6 and 8 digit)

FEMA Regions

Climate Divisions

  • Use the climate division’s ID number

[start date] and [end date]

Use the following date format M/D/YYYY for the start date and end date

[drought level]

Drought Level Value
D0 0
D1 1
D2 2
D3 3
D4 4

[minimum threshold]

The minimum percent of the area in the selected drought category to include (0-100)

[maximum threshold]

The maximum percent of the area in the selected drought category to include (0-100)

[statistics type]

Choose between traditional or categorical statistics. Use a value of 1 for traditional or 2 for categorical.

Output Format

By default the data are output in XML format. You can specify an output format in the ACCEPT request header. The format options are XML, CSV, and JSON.

Note: Using a web browser to retrieve the data will return the data in XML format by default.

Example

If a person wanted to obtain statistics for the percent of area in drought for the total U.S. between the dates of January 1st, 2012 and January 1st, 2013 in traditional format where the minimum percent of D1 is 10% and the maximum percent of D1 is 70%, the URL would look like the following:

https://usdmdataservices.unl.edu/api/USStatistics/GetBasicStatisticsByAreaPercent?aoi=TOTAL&dx=1&DxLevelThresholdFrom=10&DxLevelThresholdTo=70&startdate=1/1/2012&enddate=1/1/2013&statisticsType=1

Weeks in Drought


Get the number of weeks in drought greater than a selected threshold for selected U.S. counties. This can be done based either on consecutive weeks in drought or non-consecutive weeks in drought.

URL Structure

https://usdmdataservices.unl.edu/api/ConsecutiveNonConsecutiveStatistics/[consecutive or non-consecutive]?aoi=[aoi]&dx=[drought level]&minimumweeks=[threshold]&startdate=[start date]&enddate=[end date]

An explanation of each of the variables in the above URL is given below.

[consecutive or non-consecutive]

Data Type Value
Consecutive Weeks in Drought GetConsecutiveWeeksCounty
Non-consecutive Weeks in Drought GetNonConsecutiveStatisticsCounty

[aoi]

Use the two letter abbreviation for the state(s) or leave blank to get data for all states. If you want to use multiple states, separate the FIPS codes with a comma (01,02).

Parameter = aoi

[start date] and [end date]

Use the following date format M/D/YYYY for the start date and end date

Use the following date format M/D/YYYY

[drought level]

Drought Level Value
D0 0
D1 1
D2 2
D3 3
D4 4

[threshold]

The number of weeks in the specified drought category.

Output Format

By default the data are output in XML format. You can specify an output format in the ACCEPT request header. The format options are XML, CSV, and JSON.

Note: Using a web browser to retrieve the data will return the data in XML format by default.

Example

The example below will return the counties in Nebraska that were in drought for at least four weeks from January 1st 2013 to January 1st, 2013. In this case the four weeks did not have to occur consecutively.

https://usdmdataservices.unl.edu/api/ConsecutiveNonConsecutiveStatistics/GetNonConsecutiveStatisticsCounty?aoi=NE&dx=0&minimumweeks=4&startdate=1/1/2012&enddate=1/1/2013