Query string parameters

Users may wish to customize the information returned in the flatfile. For example, 50 rows may be too small, or users might be interested in a specific event, or may want to limit the output to certain fields. Customization can be obtained using query string parameters. The format for the query string is illustrated below.

base_url/service?query_string

If multiple query strings are desired, they should be separated by an “&” like this:

base_url/service?query_string1&query_string2

The query string parameters are service-dependent, as described for each service in the sections below. The format query string is common among all services, and may be set to html, json, or csv. The default is html, which renders a table or set of tables that can be viewed in a web browser. JSON stands for JavaScript Object Notation, and is a data-interchange format that is easy for humans to read and for computers to parse. If you’d like to incorporate our ground motion database into a computer script, json is likely the format you’ll want to use. As an example, you can use the python requests package to retrieve data from the API. The csv file format is convenient if you’d prefer to save a copy of the data to your computer. The database is constantly changing, and creating csv copies may be desired for data reproducibility.

schema

The following query string parameters are supported for the schema service:

  1. format: Controls the output format. Options are html, json, csv. If format=csv is provided as a query string, each table will be in a separate csv file, and a zip file containing those csv files will be returned.

  2. tables: Controls the tables described by the query. The query string should be a comma-separated list with no spaces. Options include all tables in the database.

  3. table_list: Controls whether a list of tables in the database is included as the first table. Default = true. May be either true or false.

flatfile

The flatfile service has a significant number of different options so users can customize the output. Those options are:

  1. format: Controls the output format. Options are html, json, csv. The default value is html.

  2. limit: Controls the number of rows returned. Default=50. Must be an integer. There is a limit to the amount of information that can be transferred through the API, so it’s possible that your request will be denied if it includes a large amount of data. But you can always break it into multiple queries if needed.

  3. offset: Controls the starting index of the returned data. Default=0. Must be an integer. This may be useful if your data request is too large to be returned by a single query because you can use the offset parameter to get sequential batches of data.

  4. tables: Controls which tables are returned in the query. Default = event,event_type,network,station,site,motion,time_series_metadata,intensity_measure,and response_spectra. Should be specified as a comma-separated list with no spaces. If a single table is listed, data will be returned for that table only. If more than one table is specified, those tables must be joined through foreign key / primary key relationships, and you may end up with data from more tables than you specified if the tables are not directly linked by key logic. See the section called Key logic for a discussion of the relationships between tables.

  5. fields: Controls which fields are returned in the query. Should be specified as a comma-separated list with no spaces. By default, every field in every table is returned, with the exception of foreign keys. The value of field can be set to any value present in any database table. If a field is specified, the table containing that field will automatically be added to the query such that the “tables” query string parameter does not need to be specified in order to use the “fields” query string parameter. Of course, both can be specified if you wish to do so.

  6. <field>: Controls the range of values for a specific field. The format depends on the field. Ranges should be separated by “-”. For example, to return a flatfile with RotD50 PGA values between 0.1 and 0.2g, the query string is pga_rotd50=0.1-0.2. Multiple field parameters can be included. For example pga_rotd50=0.1-0.2&magnitude=5-6. The only fields that cannot be specified are text fields which may contain spaces (such as station_name).

  7. component: Controls the type of component(s) for the returned intensity mesure and / or response spectra. Should be specified as a comma-separated list with no spaces. Default = rotd50. Options are h1, h2, v, rotd0, rotd50, and rotd100.

  8. period: Controls the period range in seconds of response spectra to be returned. Range should be separated by “-”. Default is the maximum range of periods in the response spectra table = 0.01-20.

  9. frequency: Controls the frequency range in Hz of the fourier spectra to be returned. Range should be separated by “-”. Default is the maximum range of frequencies in the fourier response table = 0.01318257-100

  10. sortby: Controls the field by which to sort the data. Default = the primary key of the table at the highest level of the foreign key chain (see Key logic). Data can be any field except Sa, or any fields in the fourier_spectra and acc tables.

  11. order: Controls whether the sortby field should be ascending (order=ASC) or descending (order=DESC). Default = ASC.

  12. fill_null: Controls the number to be inserted into null fields. default = NULL. In the various NGA projects, -999 is often used to fill null fields. Just be sure that the value you select for fill_null cannot be mistaken for a real value of the field (e.g., don’t set fill_null=0.1).

  13. (Coming soon, but not yet implemented!) truncate_longest_usable_period: Controls whether response spectra values are truncated beyond the longest usable period. Default = true. Only applicable if parse_json=true, and the value of fill_null will replace spectral ordinates. Ground motion records must be high-pass filtered prior to computing response spectra. Often, the low-frequency portion of the signal is dominated by noise, which causes erroneous long-period spectral accelerations. However, the response spectra stored in the database are computed to T=20s regardless of the longest usable period.

NOTE: Response spectra and fourier spectra data are stored in rows of spectral ordinates which cannot currently be used in the <field> query string. For example, spectral acceleration at 3s is not a field in the database that can be added to the query string. If you wish to do this level of data processing, you should query the data you need and subsequently perform the necessary operations on your computer. (Future versions of the API will allow such queries).

timeseries

The following query string parameters are supported for the timeseries service:

  1. format: Controls the output format. Options are AT2 and json. The default value is AT2 which will download a zip folder containing the AT2 files for the selected components and a csv containing simple metadata information.

  2. components: Controls the component(s) to be returned. Should be specified as a comma-separated list with no spaces. Default = h1,h2,v.

URL Builder

We have developed an interactive tool that will help you become familiar with building URL's. The purpose of the URL Builder Tool is help users build custom URL's for each of the services described on this page. Note that the tool has some limitations with regards to which query string options can be used. For example, the tool does not currently allow users to specify desired fields, although these can be easily added by appending "&fields={insert comma separated list of fields}" to the end of the given URL.