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)"

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, and that match the published flatfiles.

The tables listed below are queried and presented in a "flattened" form via the flatfile endpoint. If users do not specify a select, sort, or where key that identifies the ground motion component, the Rotd50 component is used by default. If users specify a select field, the selected fields are returned along with the primary keys for all tables involved in the query. Other components can be queried instead by adding a "component" query string parameter to explicitly specify the component (e.g., "?component=PsaRotd100"), or by simply including a separate query string parameter that uses data from the table you wish to query (e.g., "?sort=psa_rotd100_0p010). In the latter case, the table(s) will be inferred from the provided query strings. Note that you can request data from multiple psa tables and the eas table. However, you should recognize that doing so may result in an amount of data that is too large to be provided by the server, or may result in slow response times.

Tables included in flatfile endpoint query

Example Queries

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 1

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

example 2

Query 20 events sorted in descending order by magnitude where magnitude is between 5 and 6
https://www.gmdatabase.org/events?limit=20&sort=magnitude&direction=desc&where=(magnitude>5.0+AND+magnitude<6.0)

example 3

example 4

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/psaRotd50?limit=20&sort=psa_rotd50_0p100&direction=desc

Possible Problems

Requesting huge amounts of data

role

Floats/Doubles and =, IN, NOT IN

Filters that return no data