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/resource?query_string If multiple query strings are desired, they should be separated by an "&" like this: base_url/resource?query_string1&query_string2 The query string parameters are resource-dependent, as described for each resource in the sections below. The format query string is common among all resources, 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. .. _JSON: https://www.json.org/json-en.html schema ------ The following query string parameters are supported for the schema resource: 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 are acc, basin_model, basin_site, collection, collection_motion, component, event, event_type, finite_fault, finite_fault_seg, fourier_spectra, intensity_measure, motion, network, resp_spectra, site, station, station_ssn, time_series. 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 resource 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,intensity_measure,component,resp_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 :doc:`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. : 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 PGA values between 0.1 and 0.2g, the query string is PGA=0.1-0.2. Multiple field parameters can be included. For example PGA=0.1-0.2&magnitude=5-6. The only field that cannot be specified is Sa. 7. 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 :doc:`key_logic`). Data can be any field except Sa, or any fields in the fourier_spectra and acc tables. 8. order: Controls whether the sortby field should be ascending (order=ASC) or descending (order=DESC). Default = ASC. 9. parse_json: Controls whether spectral acceleration values are parsed from their native json format into a column format. Response spectra are stored in the database as json strings because different sets of natural periods are often used to compute response spectra. Structuring tables with fixed columns is therefore not feasible, and would result in a lot of null fields in the database. If parse_json=true, the json strings will be parsed into columns. The number of columns will equal the number of different natural periods or frequencies in the query. Many fields may be null if response spectra with different sets of natural periods are queried. 10. fill_null: Controls the number to be inserted into null fields when parsing the response spectra json strings. default = NULL. Only applicable if parse_json=true, and will only fill null fields in the resp_spectra table. 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). 11. (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 data are stored in json strings, and values of spectral ordinates cannot be used in the 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.