Vs30 Developer Information

Overview

The Vs30 application provides a simple web API to allow developers to incorporate its calculations into their own software. Developers can provide a set of parameters - the same set as on the custom vs30 mapping page - and the API will return a JSON object with links to the generated files.

Making a request

Access to the web API is handled through HTTP requests. The process of making a request varies between languages, so you will need to find the relevent methods or libraries in your language.

Requests need to be made to the Vs30 processing page, located at http://earthquake.usgs.gov/hazards/apps/vs30/vs30.php. The request must include all of the following POST parameters.

json - Specifies that the results should be returned as a JSON object. Otherwise, results will be a formatted HTML string. This should always be set to "true".
site_name - Name of the site you are generating Vs30 maps for. This must be a string. Generated files will be named site_name.jpg, site_name.grd.gz, and site_name.xyz.gz.
top_left_lat - Latitude of the northeast corner of the mapping region's rectangle.
top_left_lon - Longitude of the northeast corner of the mapping region's rectangle.
bottom_right_lat - Latitude of the southwest corner of the mapping region's rectangle.
bottom_right_lon - Longitude of the southwest corner of the mapping region's rectangle.
slope_type - Must be set to either "active", "stable", or "custom". If slope_type is set to "custom", the slopes variable must be set (see below).
slopes - Only required if slope_type is set to "custom". This must be set to an array of 7 values. The values should be m/m corresponding to Vs30 measurements of 180m/s, 240m/s, 300m/s, 360m/s, 490m/s, 620m/s and 760m/s respectively.
output_types - Array of output formats to generate. This array must contain any combination of "jpg", "xyz", and "grd".

Results

Once you have made a request successfully with all the proper parameters, the API will return a JSON object containing the generated files. If the calculation ran successfully, the response object will be in the form:

	{
		"jpg": {
			"url":   <string containing full path to file> ,
			"size":  <number of bytes>,
			"thumb": <path to 80px wide thumbnail>
		},
		"grd": {
			"url":   <string containing full path to file> ,
			"size":  <number of bytes>
		},
		"xyz": {
			"url":   <string containing full path to file> ,
			"size":  <number of bytes>
		}
	}

The JSON object will only include the "jpg", "grd", and "xyz" objects if they are specified by the output_types parameter.

If for some reason the calculation failed (usually if one or more parameters are missing), the response object will be in the following form. Each item in the "errors" array describes one error encountered.

	{
		"errors": ["error 1", "error 2", "..."]
	}

Caveats

In the returned strings, all html special characters will be escaped. This really only applies to slashes ("/").

The site name will be sanitized. Characters in the following list are removed from the filename: "#", "$", "%", "^", "&", "*", "!", "~", "‘", "\"", "’", "'", "=", "?", "/", "[", "]", "(", ")", "|", "<",">", ";", "\", ",", and ".". Spaces will be replaced with underscores.