Application Programming Interface

The ground motion database is equipped with a web interface, which is what you are currently viewing, and an application programming interface (API) that exposes the data to HTTP requests. The web interface is useful if you quickly want to look at data in a tabular form, but it is cumbersome if you want to develop an end-to-end workflow. Copying HTML tables is kind of a pain, and it takes time to render those tables. The API exposes the underlying data through HTTP requests, providing the data in JSON format so you can work with it more directly and incoporate it into a workflow.

Users can access the API by authenticating, retrieving an authorization token, and submitting a request that includes that token in the request header. The authorization token is required because we want to make sure that we return the information only to people who have an active account, thereby avoiding attacks by unauthorized users, and that users have access to data consistent with their role (user, modeler, admin).

Authentication / Authorization

The first step in using the API is to authenticate and retrieve an authorization token. To authenticate, submit an API request to the following uniform resource locator (URL)

https://www.gmdatabase.org/users/login

You must use the Basic Auth method to include your username and password with the HTTP request. Programs specifically designed for making HTTP requests include curl, postman, and others. In this documentation, we provide examples using the Python requests package. The example below authenticates the user using HTTP Basic Auth and retrieves an authorization token. We suggest never hard-coding your username and password into a script. You might accidentally share the script, and divulge your authentication credentials. We have used the getpass package here facilitate password entry. The token is valid for 120 minutes, after which you will need to re-authenticate and retrieve a new token. It is important not to share your token with others.

                    import requests
                    from requests.auth import HTTPBasicAuth
                    import getpass
                    import json

                    username = input('username: ')
                    password = getpass.getpass('password: ')
                    url = 'http://www.gmdatabase.org/users/login'
                    headers = {"User-Agent":"XY", "Accept":"application/json"}
                    r = requests.get(url, headers=headers, auth=HTTPBasicAuth(username,password))
                    token = json.loads(r.text)['token']

                

Submitting a Request

After retrieving an authorization token, you can now submit a GET request to the desired URL, and the requested data will be returned in JSON format. Two headers must be included in your request. The "Accept":"application/json" header is used to identify that JSON data is being requested. The "Authorization":"Bearer {}".format(token) header contains the authorization token that was provided after successful authentication.
An example request is provided in the Python script below. In this case, the API requests 50 entries from the events table. The URL structure and available query string parameters for customizing the request are discussed in the next section.

                    
                        import pandas as pd
                        import requests
                        import json

                        headers = {"Accept":"application/json","Authorization": "Bearer {}".format(token)}
                        url = 'http://www.gmdatabase.org/events?limit=50'
                        r= requests.get(url, headers=headers)
                        df = pd.DataFrame.from_dict(json.loads(r.text))

                    
                

URL structure

Requests are submitted to a uniform resource locator (URL) that contains the following components:

url = base_url/endpoint?query_string

"?where=hypocenter_latitude<40+OR+hypocenter_longitude>-118.0"

"?where=(hypocenter_latitude>40.0+AND+hypocenter_latitude<42.0)+OR+(hypocenter_longitude>-118.0+AND+hypocenter_longitude<-117.0)"

"where=hypocenter_latitude>40.0+AND+hypocenter_latitude<42.0"

"where=latitude+BETWEEN+40.0+AND+42.0"

responseSpectra and fourierSpectra endpoints

sorting

filtering

components

flatfile endpoint

The database is organized into many different tables to ensure data integrity, but users often want to query data from multiple tables and join them together in a way that results in repetition of certain fields. For example, users might want to retrieve all event, site, and ground motion data together in the same table, where event and site information is repeated for each ground motion. The flatfile endpoint provides the logic to join together tables that we believe will serve the needs of most users. Specifically, the following tables are queried and presented in a "flattened" form via the flatfile endpoint. By default, the fourier_spectra table is not queried, but can be included by specifying query string parameters as indicated below.

Tables included in flatfile endpoint query

Query string parameters for the flatfile table are a bit more complicated than for the individual tables. A list of available query string parameters and their default values is indicated below. Desired components are specified separately for the intensity_measure, response_spectra, and fourier_spectra tables. It might be cumbersome to specify these separately, but it is not straightforward to infer user intent from a single set of components. For example, if we used a single "components" query string parameter, and a user specified "h1", we would not know if they want fourier_spectra or response_spectra. For clarify, we have separated them, at the expense of longer query strings. Users might not want to return all of the fields in the flatfile. For example, if a user specifies "?fields=psa_rotd50_0p10", they will retrieve only the RotD50 spectral accelerations at T=0.1s. However, we include primary keys from each table because it would otherwise be very difficult to make sense of the resulting table.

query string options for flatfile endpoint

Whether data are included from response_spectra, fourier_spectra, or both is inferred from the provided query string parameters. For example, if you specify response_spectra_components, and fourier_spectra_components in the query string, both will be returned. Furthermore, if you include response_spectra or fourier_spectra quantities in the sort, fields, or [field name] query string parameters, those data will be returned. For example, ?psa_rotd50_0p10>0.1&sort=eas_0p10 will return all of the RotD50 response spectral ordinates, and all of the eas Fourier spectra ordinates (unless the "fields" query string parameter is used to reduce the list of returned fields). If you specify "fields", only those fields will be returned, whereas if "fields" is omitted, all fields in each table will be returned.

Example Queries

example 1

Below are a few example queries that show how to specify endpoints and query string parameters. This is not an exhaustive list, but just a few examples.

example 2

Query 20 events sorted in descending order by magnitude:
https://www.gmdatabase.org/events?limit=20&sort=magnitude&direction=desc

example 3

Query 20 results for the rotd50 response_spectra component sorted in descending order by spectral acceleration at 0.1 second period:
https://www.gmdatabase.org/responseSpectra?limit=20&sort=psa_rotd50_0p100&direction=desc

example 4

Query results 40-60 (i.e., the 3rd page with limit=20) for the RotD50 and h1 response_spectra components sorted in descending order by RotD50 spectral acceleration at 0.1 second period:
https://www.gmdatabase.org/responseSpectra?limit=20&sort=psa_rotd50_0p10&direction=desc&components=psa_rotd50,h1&page=3

example 5

Query results 40-60 for the RotD50 response_spectra components sorted in descending order by RotD50 spectral acceleration at 0.1 second period for values with Rotd50 spectral acceleration at 0.01s less than 0.1g.
https://www.gmdatabase.org/responseSpectra?limit=20&sort=psa_rotd50_0p10&direction=desc&psa_rotd50_0p01>0.1&page=3

We don't know why anyone would want to limit and sort by spectral acceleration at different natural periods, but we're not judgy. This is just demonstrating how to use the query string fields.

example 6

Query response_spectra flatfile for the RotD50 components sorted in descending order by RotD50 spectral acceleration at 0.1 second period.
https://www.gmdatabase.org/flatfile?sort=psa_rotd50_0p10&direction=desc

We don't know why anyone would want to limit and sort by spectral acceleration at different natural periods, but we're not judgy. This is just demonstrating how to use the query string fields.

Possible Problems

Requesting huge amounts of data

role

Floats and =

Filters that return no data