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 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, and avoid attacks by unathorized users.

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 to prevent that by requiring users to enter their credentials each time the code is executed. 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 ingredients:

url = base_url/endpoint?query_string

base_url

The base_url is the webpage containing the API. In this case, it is



https://www.gmdatabase.org

Submitting a request without also specifying an endpoint will produce an error. The endpoint is necessary so we know which query to run to retrieve the data you have requested. The query string is optional, and can be used to customize your queries.

endpoint

An endpoint is a location where an API receives requests about a resource. The endpoints correspond to table names converted to pluralized lower camel case with underscores removed. All of the tables except for the user table are accessible. The user table is not accessible for privacy purposes. Furthermore, a flatfile endpoint is also available. The flatfile endpoint combines tables together in a manner similar to the NGA flatfiles. Tables included in the flatfile endpoint are indicated with a checkmark in the table below. The flatfile can be generated either for the response_spectra table or the fourier_spectra table, but not both at the same time because the resulting table would be large and unwieldy.



table name	endpoint	table included in flatfile
aftershock_mainshock	aftershockMainshocks
basin_model	basinModels
basin_site	basinSites
citation	citations
collections	collections
collection_motion	collectionMotions
event	events	✔
event_eqid	eventEqids	✔
event_geometry	eventGeometries
event_type	eventTypes	✔
finite_fault	finiteFaults	✔
finite_fault_kinematic_parameter	finiteFaultKinematicParameters	✔
finite_fault_segment	finiteFaultSegments
fourier_spectra	fourierSpectra	(✔)
intensity_measure	intensityMeasures	✔
motion	motions	✔
network	networks	✔
path	paths	x
response_spectra	responseSpectra	(✔)
site	sites	✔
site_geometry	siteGeometries
station	stations	✔
station_ssn	stationSsns	✔
time_series_data	timeSeriesData
time_series_metadata	timeSeriesMetadata	✔
version	versions
version_time_series_metadata	versionTimeSeriesMetadata	✔
vs30_citation	vs30Citations
vs30_code	vs30Codes
z_code	zCodes

query_string

A query string is a list of parameters used to customize the request. If a query string is not specified, default values will be returned. A list of valid query string parameters and their default values is below. The flatfile endpoint uses different query strings than the table endpoints. See the flatfile section for more details.



query string options for table endpoints

query string parameter	default	description
limit	20	number of records per page
sort	primary_key	field to sort by
direction	asc	sort direction (asc or desc)
page	1	page number
role	user	Only used for API. Dropdown used to set role for website.
components	psa_rotd50, or eas	see response_spectra and fourier_spectra section
[field name]	-	Used to filter fields (e.g., ?pga_rotd50>0.1




First query string parameter

The first query string parameter comes after a question mark (?) at the end of the url. For example: https://www.gmdatabase.org/intensityMeasures?page=1.



Second and subsequent query string parameters

The 2nd and subsequent query string parameters are separated by an ampersand (&). For example: https://www.gmdatabase.org/?page=1&limit=50.



Filtering data using field names

Each field name query string parameter has three parts: field_name, delimiter, value. Valid delimiters include the following: [<, >, =, <=, >=]. For example ?pga_rotd50>0.1 will return entries that have peak acceleration for the RotD50 component greater than 0.1. You can include as many field names as you want. For example, ?pga_rotd50>0.1&pga_rotd50<0.2 will return all PGA values for the RotD50 component greater than 0.1 and less than 0.2. You can also include strings and datetime fields. For example https://gmdatabase.org/events?event_name>h will return fields with event name beginning with the letter "H" or higher in the alphabet. Furthermore, https://gmdatabase.org/events?datetime>01/01/1990 will return events that occurred after January 1, 1990.

response_spectra and fourier_spectra tables

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 together. For example, users might want to retrieve all event, site, and ground motion data together in the same table. 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