The Medeek API

Introduction
What Can You Do with the Medeek API?
Audience
Usage Limits
API Key
Requests
- Output Formats
- Parameter Usage
Bulk Requests
Responses

Introduction

Welcome to the developer documentation for the Medeek API. The Medeek API provides you a simple interface to query locations in the United States for geographic, seismic and climate data.

What Can You Do with the Medeek API

The Medeek API currently provides the following data for any location in the contiguous United States (lower 48), Alaska and Puerto Rico:

ASCE ground snow load data (lower 48 states only)
IRC 2012 seismic data
IBC 2012 seismic data
IRC 2012 wind data
ASCE 7-10 wind data
ASCE 7-05 wind data

Ground snow load data is based on Figure 7-1 of the ASCE 7-10. Seismic data is initially retreived from the USGS Seismic Design API and used to compute the appropriate Seismic Design Category. ASCE Wind speeds are based on Figures 26.5-1A, 26.5-1B and 26.5-1C of the ASCE 7-10 and Figure 6-1 of the ASCE 7-05. IRC 2012 wind speeds are calculated from the ASCE Risk Category II ultimate wind speed.

The API has also been recently updated and expanded to provide local snow load data for the following regions:

Massachusetts
Montana
New York
Utah
Nevada County, CA (with Truckee, CA)
Michigan

Local ground snow load data is based on State, County and Municipal building codes and is often derived from snow load studies commissioned by the structural engineering associations within the state or jurisdiction. The specific source of the local snow load data is provided as part of the API output when the local data option is selected.

Given an exact location (Latitude, Longitude) the API can provide accurate ground snow load, wind load or seismic data as well as elevation information.

With the Medeek API, you can develop roofing, building, solar panel or other construction related applications that rely on accurate ground snow load, wind load or seismic data. Please feel free to download and test the following sample applications listed below:

ASCE 7-10 Wind Lookup Tool (Microsoft Excel Spreadsheet with VBA)

You can access the Medeek API through an HTTP or HTTPS interface.

Audience

This document is intended for website and mobile developers who want to use ASCE ground snow load data, ASCE wind load data, IRC 2012 seismic data or IRC wind load data within their own web based or mobile applications. It provides an introduction to using the API and reference material on the available parameters.

Usage Limits

The Medeek API has the following limits in place:

API Key required for all requests.
1000 requests per 24 hour period.
1 location per request.

These limits are enforced to prevent abuse and/or repurposing of the Medeek API, and may be changed in the future without notice. Additionally, we enforce a request rate limit to prevent abuse of the service. If you exceed the 24-hour limit or otherwise abuse the service, the API may stop working for you temporarily. If you continue to exceed this limit, your access to the Medeek API may be blocked.

If you need a higher usage limit please contact us in order to make special arrangements.

API Key

All Medeek API applications should use an API key ($300.00 per year). All keys are managed through the Medeek Account Manager. To create your key:

Visit the Medeek Login page and log in with your Medeek Client Profile or Register a new profile.
Click the Services from the left-hand menu in the Account Manager, then purchase the Medeek API service.
Once the service has been activated, your API key is available from the Medeek API page, in the Services section.

To specify a key in your request, include it as the value of the key parameter.

For testing purposes please use the following key: MEDEEK12721119

Requests

A Medeek API URL must be of the following form:

http://design.medeek.com/resources/medeekapi.pl?parameters

Tip: You can also access the Medeek API using SSL, by substituting https for http in the request URL. HTTPS is recommended for applications that include sensitive user data, such as a user's location, in requests.

Output Formats

Outputs formats are specified using the optional output parameter in the request URL. The Medeek API currently supports the following output formats:

output=json returns results in JavaScript Object Notation (JSON).
output=xml returns results in XML, wrapped within a node.
output=text returns results in plain text form. If output parameter is omitted this is the default output format.

Parameter Usage

Requests to the Medeek API utilize different parameters based on whether the request is for ASCE or State ground snow loads.

As is standard in all URLs, parameters are separated using the ampersand (&) character. The list of parameters and their possible values are denoted below.

action (required) specifies whether the application is requesting ASCE ground snow load, IRC seismic design category or IRC/ASCE wind loads. Possible values are ascesnow, irc2012seismic, ibc2012seismic, irc2012wind, asce710wind or asce705wind.
key (required) your application's API key. Purchase a key in the Account Manager.
lat (required) The latitude of the location in the contiguous US from which to return ground snow load data. This parameter takes a single numerical value (e.g. "44.714728")
lng (required) The longitude of the location in the contiguous US from which to return ground snow load data. This parameter takes a single numerical value (e.g. "-123.916532")
output (optional) specifies the output format required.
localdata (optional - ASCE Snow) enables local snow load data lookup for specific locations. Assign a value of 1 to acquire local snow load data.
siteclass (required - IBC 2012 Seismic) specifies the site soil classification. Site class "D" is typical for most construction sites.

Input Value Meaning

A Site Class A – “Hard Rock”

B Site Class B – “Rock”

C Site Class C – “Very Dense Soil and Soft Rock”

D Site Class D – “Stiff Soil”

E Site Class E – “Soft Clay Soil”

riskcat (required - IBC 2012 Seismic) specifies the risk category used to compute the seismic design category. A risk category of II is typical for most low rise and residential structures.

Integer Value Meaning

1 I - Low Hazard

2 II - Other

3 III - Substantial Hazard

4 IV - Essential

edition (optional - IBC 2012 Seismic) specifies which seismic provisions to use. If unspecified the default seismic provisions are taken from the IBC 2012.

Input Value Meaning

ibc-2012 2012 International Building Code

asce-2010 ASCE 7-10 Standard

aashto-2009 2009 AASHTO Guide for LRFD Seismic Bridge Design

ibc-2009 2006/2009 International Building Code

nehrp-2009 2009 NEHRP Recommended Seismic Provisions

asce-2005 ASCE 7-05 Standard

nehrp-2003 2003 NEHRP Recommended Seismic Provisions

Bulk Requests

If you are in need of a static database of various site criteria for specific locations you can supply us with a comma deliminated spreadsheet or text file of the latitude and longitude of each location. Please specify the site criteria that you require. The cost for this service is currently $50.00 per 1,000 data points. Please contact us directly to request this service and discuss the details.

Responses

For each valid request, the Medeek API service will return a response in the format indicated by the ouput parameter. Each response will contain the following elements:

A status code, which may be one of the following:

OK indicating the API request was successful.
INVALID_REQUEST indicating the API request was malformed or the action parameter was not properly specified.
OVER_QUERY_LIMIT indicating the requestor has exceeded quota for that 24 hour period.
ACCESS_DENIED indicating the API did not complete the request, likely because the requestor failed to include a valid API key.
UNKNOWN_ERROR indicating an unknown error.

When the status code is other than OK, there may be an additional error_message field within the response object. This field contains more detailed information about the reasons behind the given status code.

Note: This field is not guaranteed to be always present, and its content is subject to change.

An array of results containing the following applicable elements:

A pg element indicating the ground snow load for that location.
An sdc element indicating the seismic design category for that location.
An sds element indicating the design spectral response acceleration for that location (Site Class = D, Risk Cat. = II).
A windasd element indicating the IRC 2012 basic wind speed for that location.
A windi element indicating the ASCE 7-10 basic wind speed (Risk Category I) for that location.
A windii element indicating the ASCE 7-10 basic wind speed (Risk Category II) for that location.
A windiii element indicating the ASCE 7-10 basic wind speed (Risk Category III) for that location.
A wind05 element indicating the ASCE 7-05 basic wind speed for that location.
An elevation element indicating the elevation of the location in feet (as determined by Google Elevation API).
A keyexp element indicating the expiration data (mm/yyyy) of your API key.
A requests element indicating the number or requests that are still available for that 24 hour period.

*Note: The IBC seismic option requires two extra input parameters and has a number of additional results that are specific to seismic design, see IBC 2012 Seismic Example below.

Enabling the localdata lookup option for ASCE Ground Snow Load will produce the following three additional results:

A pg_local element indicating the local ground snow load for that location.
A source_local element indicating the source of the local ground snow load for that location.
A revgeo element indicating the reverse geolocation of the coordinates provided.

*Note: If the localdata option is enabled, and no local snow data is available for that location, the applicable results will display "NO DATA".

ASCE Ground Snow Load Example

The following example requests the ASCE Ground Snow Load for Denver, Colorado, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=ascesnow&key=MEDEEK12721119&lat=39.7376&lng=-104.9847


ASCE Ground Snow Load:
20 psf
Elevation: 5273.8 ft
Key Expiration: 3/2016
Requests: 1265
Status: OK

IRC 2012 Seismic Example

The following example requests the IRC 2012 Seismic Design Category for Provo, Utah, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=irc2012seismic&key=MEDEEK12721119&lat=40.2338&lng=-111.6585


IRC 2012 SDC: D1
SDS: 0.824
Elevation: 4551.1 ft
Key Expiration: 3/2016
Requests: 1478
Status: OK

IRC 2012 Wind Example

The following example requests the IRC 2012 Basic Wind Speed for St. Louis, Missouri, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=irc2012wind&key=MEDEEK12721119&lat=38.6270&lng=-90.1994


IRC 2012 Basic Wind Speed: 90 mph
Elevation: 462.4 ft
Key Expiration: 3/2016
Requests: 1478
Status: OK

ASCE 7-10 Wind Example

The following example requests the ASCE 7-10 Wind Speeds for Miami, Florida, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=asce710wind&key=MEDEEK12721119&lat=25.7890&lng=-80.2264


ASCE 7-10 Wind Speeds
Risk Category I: 156 mph
Risk Category II: 168 mph
Risk Category III-IV: 180 mph
Elevation: 4.0 ft
Key Expiration: 3/2016
Requests: 1477
Status: OK

ASCE 7-10 Wind Example (XML)

The following example requests the ASCE 7-10 Wind Speeds for Chicago, Illinois, in xml format:

https://design.medeek.com/resources/medeekapi.pl?action=asce710wind&key=MEDEEK12721119&lat=41.8781&lng=-87.6298&output=xml


<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>OK</status>
 <result>
  <location>
   <lat>41.8781</lat>
   <lng>-87.6298</lng>
  </location>
  <windi>105 mph</windi>
  <windii>115 mph</windii>
  <windiii>120 mph</windiii>
  <elevation>594.8</elevation>
  <keyexp>3/2016</keyexp>
  <requests>1434</requests>
 </result>
</response>

ASCE Ground Snow Load Example (JSON)

The following example requests the ASCE Ground Snow Load for Las Vegas, Nevada, in json format:

https://design.medeek.com/resources/medeekapi.pl?action=ascesnow&key=MEDEEK12721119&lat=36.1379&lng=-115.2040&output=json


{
   "results" : [
      {
         "elevation" : 2200.5,
         "location" : {
            "lat" : 36.1379,
            "lng" : -115.2040
         },
         "pg" : "(6000 ft.) 15 psf,(4500 ft.) 10 psf,(3600 ft.) 5 psf,(2000 ft.) 0 psf",
         "keyexp" : "3/2016",
         "requests" : "1427"
      }
   ],
   "status" : "OK"
}

ASCE 7-05 Wind Example (XML)

The following example requests the ASCE 7-05 Wind Speeds for Chicago, Illinois, in xml format:

https://design.medeek.com/resources/medeekapi.pl?action=asce705wind&key=MEDEEK12721119&lat=41.8781&lng=-87.6298&output=xml


<?xml version="1.0" encoding="UTF-8"?>
<response>
 <status>OK</status>
 <result>
  <location>
   <lat>41.8781</lat>
   <lng>-87.6298</lng>
  </location>
  <wind05>90 mph</wind05>
  <elevation>594.8</elevation>
  <keyexp>5/2016</keyexp>
  <requests>1323</requests>
 </result>
</response>

IBC 2012 Seismic Example

The following example requests the IBC 2012 Seismic Design Category for Provo, Utah, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=ibc2012seismic&key=MEDEEK12721119&lat=40.2338&lng=-111.6585&siteclass=D&riskcat=2


IBC 2012 SDC: D
SDS: 0.824
SD1: 0.463
SS: 1.222
S1: 0.447
SMS: 1.236
SM1: 0.694
FA: 1.011
FV: 1.553
TL: 8
RISKCAT: II - Other
SITECLASS: Site Class D - "Stiff Soil"
EDITION: ibc-2012
Elevation: 4550.2 ft
Key Expiration: 05/2016
Requests: 471
Status: OK

ASCE Ground Snow Load Example (with local data)

The following example requests the ASCE and Local Ground Snow Load for Truckee, California, in plain text format:

https://design.medeek.com/resources/medeekapi.pl?action=ascesnow&key=MEDEEK12721119&lat=39.3529&lng=-120.1265&localdata=1


ASCE Ground Snow Load:
Site-specific case study (CS) required to establish ground snow load at this location.
Local Snow Load: 190.0 psf
Source: Town of Truckee Municipal Code: Title 15 Table 1608.4
Geolocation: Truckee,Nevada,CA
Elevation: 5700.3 ft
Key Expiration: 05/2016
Requests: 419
Status: OK

If you have any questions or concerns about the API service please call us at 1-425-741-5555.

Input Value	Meaning
A	Site Class A – “Hard Rock”
B	Site Class B – “Rock”
C	Site Class C – “Very Dense Soil and Soft Rock”
D	Site Class D – “Stiff Soil”
E	Site Class E – “Soft Clay Soil”

Integer Value	Meaning
1	I - Low Hazard
2	II - Other
3	III - Substantial Hazard
4	IV - Essential

Input Value	Meaning
ibc-2012	2012 International Building Code
asce-2010	ASCE 7-10 Standard
aashto-2009	2009 AASHTO Guide for LRFD Seismic Bridge Design
ibc-2009	2006/2009 International Building Code
nehrp-2009	2009 NEHRP Recommended Seismic Provisions
asce-2005	ASCE 7-05 Standard
nehrp-2003	2003 NEHRP Recommended Seismic Provisions