Technical Documentation for Using the IGWS API Services by Gary Motz

On this page, you will find additional information on the following subjects. Each link will allow you to jump to the appropriate subsection.

Springs API Parameters

The following parameters can be used to filter API returns according to the formats specified below. Only one parameter may be passed, or specified, per API call. The verbatim values to be passed for a 'string' format are tabulated here as well.

Parameters:
  • County — string
  • Start_date — yyyy-mm-dd hh:mm:ss
  • End_date — yyyy-mm-dd hh:mm:ss
  • Site_no — integer
  • Classification — string
  • Classification_by_discharge — string
  • Physiographic_region — string
  • Is_private — boolean("true" or 1; "false" or 0)
  • Page_length — integer
  • Page — integer
  • Format — string("json" or "xml")
SpringClassification ClassificationByDischarge PhysiographicRegion County
Cave Spring 1 Auburn Morainal Complex Adams
Contact Spring 2 Bluffton Till Plain Allen
Fracture Spring 3 Boonville Hills Bartholomew
Karst Spring 4 Central Wabash Valley Benton
Karst Spring (mineral) 5 Charlestown Hills Blackford
Solution Spring 6 Crawford Upland Boone
7 Dearborn Upland Brown
Iroquois Till Plain Carroll
Kankakee Drainageways Cass
Lake Michigan Clark
Lake Michigan Border Clay
Martinsville Hills Clinton
Maumee Lake Plain Crawford
Mitchell Plateau Daviess
Muscatatuck Plateau Dearborn
New Castle Till Plains and Drainageways Decatur
Norman Upland Dekalb
Plymouth Morainal Complex Delaware
Scottsburg Lowland Dubois
St. Joseph Drainageways Elkhart
Tipton Till Plain Fayette
Valparaiso Morainal Complex Floyd
Wabash Lowland Fountain
Warsaw Moraines and Drainageways Franklin
Fulton
Gibson
Grant
Greene
Hamilton
Hancock
Harrison
Hendricks
Henry
Howard
Huntington
Jackson
Jasper
Jay
Jefferson
Jennings
Johnson
Knox
Kosciusko
LaGrange
Lake
LaPorte
Lawrence
Madison
Marion
Marshall
Martin
Miami
Monroe
Montgomery
Morgan
Newton
Noble
Ohio
Orange
Owen
Parke
Perry
Pike
Porter
Posey
Pulaski
Putnam
Randolph
Ripley
Rush
Scott
Shelby
Spencer
St. Joseph
Starke
Steuben
Sullivan
Switzerland
Tippecanoe
Tipton
Union
Vanderburgh
Vermillion
Vigo
Wabash
Warren
Warrick
Washington
Wayne
Wells
White
Whitley

IWBN API Parameters

The parameters listed in the tables below can be used to sort API returns.

SiteID IWBN Site Name
1 CR1000_Bloomington_N
2 CR1000_Brownsburg_N1
3 CR1000_Brownsburg_N2
4 CR1000_Brownsburg_NE1
5 CR1000_FortWayne_N1
6 CR1000_FortWayne_N3
7 CR1000_Glenwood_N
8 CR1000_Indianapolis_N
9 CR3000_LakeStation_W
10 CR1000_Martinsville_N
11 CR1000_Muncie_N
12 CR1000_NewCastle_NE
13 CR1000_Rushville_S
14 CR1000_Washington_E
ParameterName Human-readable parameter name (units)
AirTC_Avg Average air temperature (C)
AirTC_Max Maximum air temperature (C)
AirTC_Min Minimum air temperature (C)
Baro_Avg Average barometric pressure (psi)
ElevationGW_m Groundwater elevation (m)
Height_of_GW_cm Height of groundwater above the pressure transducer (cm)
NR_Avg Net radiation (Watt/m^2)
Rain_mm_Tot Total precipitation (mm)
RH Relative humidity (%)
RH_Max Maximum relative humidity (%)
RH_Min Minimum relative humidity (%)
SlrMJ_Tot Average solar radiation (megaJoule)
SlrW_Avg Average solar radiation (Watt/m^2)
Temp_GW_C Groundwater temperature (C)
Tsoil_1ft_Avg Soil temperature at 1 ft (C)
TSoil_4in_Avg Soil temperature at 4 in (C)
Tsoil_6in_Avg Soil temperature at 6 in (C)
VWC_1ft_Avg Volumetric water content at 1 ft (m^3/m^3)
VWC_4in_Avg Volumetric water content at 4 in (m^3/m^3)
VWC_6in_Avg Volumetric water content at 6 in (m^3/m^3)
WindDir_Avg Wind direction (degrees)
WS_gust_Avg Gust speed (m/s)
WS_ms_Avg Average wind speed (m/s)
WS_ms_Max Maximum wind speed (m/s)


New-User Walkthrough: Springs API

Note: No authentication is necessary to use the IGWS Springs API, but there is a throttling limit of 30 requests per minute.

Hint: You can also use our Swagger UI Documentation to try out the API, including creating cURL and HTTPS requests that you can send using your terminal, command prompt, script, or HTTPS client.

  1. Send an HTTPS or cURL GET request to the Springs API: https://igws.indiana.edu/water/api/v1/springs/spring_records
    • cURL example: curl -X GET "https://igws.indiana.edu/water/api/v1/springs/spring_records" -H "accept: application/json"
    • HTTPS example: https://igws.indiana.edu/water/api/v1/springs/spring_records
  2. To filter the results by the optional parameters (see below), append a “?” to the API URL and the URL-encoded parameter plus an equal sign plus the URL-encoded parameter value. Multiple parameters should be separated by an ampersand. For example: https://igws.indiana.edu/water/api/v1/springs/spring_records?parameter1=parameter1%20value&parameter2=parameter2%20value
    • cURL example: curl -X GET "https://igws.indiana.edu/water/api/v1/springs/spring_records?classification=cave%20spring&physiographic_region=Mitchell%20plateau" -H "accept: application/json"
    • HTTPS example: https://igws.indiana.edu/water/api/v1/springs/spring_records?classification=cave%20spring&physiographic_region=Mitchell%20plateau
  3. To limit the number of springs returned per page, use the “page_length” parameter set equal to an integer, and use the “page” parameter set equal to an integer to paginate through the response pages.
  4. To have the response returned in XML, use the “format” parameter set equal to “xml”. If set to “json” or not set, it will return a response in JSON.
    • cURL example: curl -X GET "https://igws.indiana.edu/water/api/v1/springs/spring_records?format=xml" -H "accept: application/xml"
    • HTTPS example: https://igws.indiana.edu/water/api/v1/springs/spring_records?format=xml

New-User Walkthrough: IWBN API

  1. Click "Sign In" in the top right corner of the IGWS website. Create and/or verify your IGWS account if you do not have one already. Use the “Create Account” button on the Sign In pop-up on the IGWS website.
    alt text
  2. You must be granted access by the IGWS to be able to access the IWBN API endpoints. Request access for your account by emailing IGWShelp.
  3. Once access has been granted for your account, you can test authentication to the IWBN API to ensure you are receiving a valid access_token.
    • Access the IWBN API test site (Swagger user interface): https://igws.indiana.edu/water/api_doc#/.
    • Use the IWBN POST /auth/login endpoint to provide your USERNAME and PASSWORD so that you can receive an access_token. Click the "Try it out" button to enter your USERNAME and PASSWORD.
      • alt text
    • If your USERNAME and PASSWORD are valid and your account has been authorized for API access, you will receive a valid access_token in the response. For example:
      {"code": 0,
      "message": "ok",
      "data": {
        "access_token":"eyJ...97TiRBU4rAFQ",
        "token_type": "bearer",
        "expires_in": 86400,
        "is_admin": true
        }
      }
    • Copy the value given in the "access_token" field because you will use that value for subsequent requests to the IWBN API daily or hourly endpoints. The token is valid for 24 hours and requesting a new token will invalidate your previous token.
    • Select the "Authorize" button on the right side of the screen.
      • alt text
    • A pop-up will appear that asks for your access_token. Provide it by inserting the word "Bearer" and then a space before the value that you received in the access_token field in the previous step.
      • alt text
    • If successful, you will now be logged in and authorized to use the IWBN endpoints within the IWBN API test site for the current browser session.
  4. After you select the "Try it out" button, you can run queries from the two IWBN endpoints to verify that you are receiving observation data from the API:
  5. You can find information about the controlled data lists that you may use to filter your query data above.
Additional assistance with the API can be obtained by emailing IGWShelp.

Advanced-User Authentication of the IWBN API

Now that you have verified that your user credentials are valid for the IWBN API endpoints, you may use your preferred HTTP client to connect and run queries.
  1. Using a standard HTTP client, e.g., cURL or Postman, to connect to the IWBN API, send a POST request to https://igws.indiana.edu/water/api/v1/auth/login?username=USERNAME&password=PASSWORD where USERNAME is your username and PASSWORD is your password.
  2. You'll receive a JSON response like the following:
    {"code": 0,
    "message": "ok",
    "data": {
      "access_token":"eyJ...97TiRBU4rAFQ",
      "token_type": "bearer",
      "expires_in": 86400,
      "is_admin": true
      }
    }
  3. Use the "access_token" value that you receive in the JSON response for subsequent requests to the IWBN daily or hourly endpoints. Send the access_token as a "Bearer" token when making requests to the IWBN API. If using cURL, add a header flag (--header) with an Authorization object with the access_token prepended by "Bearer"
    For example:
    curl --location --request GET 'https://igws.indiana.edu/water/api/v1/iwbn/observations/hourly?site_id=3' --header 'Authorization: Bearer <access_token>'
  4. If using Postman, there's an option to use a Bearer token as Authorization. If you use that option, there is no need to use "Bearer" in front of your access_token.
  5. If you use the Swagger UI at https://igws.indiana.edu/water/api_doc#/, then you should authenticate using the "Authorize" button and insert the following text string:
    Bearer <access_token>
  6. The token will be valid for 24 hours but requesting a new token will invalidate the previous token.