navigation bar
query string parameters
api documentation sidebar

Query string parameters

Users may wish to customize the information returned in an API request. For example, the default flatfile endpoint requests information from certain tables, and returns only 50 rows. 50 rows may be too small, or users might be interested in a specific event, events within a certain magnitude range, or may want to limit the output to certain fields. Customization can be obtained using query string parameters.

For example, let's say we want information from the flatfile endpoint containing information only from the events table. We could use the link below:

https://gmdatabase.org/flatfile?tables=event

If we wanted to modify the query to include information from the motion table too, we could use the link below:

https://gmdatabase.org/flatfile?tables=event,motion

If multiple query string types are required, they should be separated by an “&” like this. For example, if we want to retrieve 1000 entries instead of 50, we could do this:

https://gmdatabase.org/flatfile?tables=event,motion&limit=1000

The query string parameters are endpoint-dependent, as described for each endpoint in the sections below.

schema

The schema resource does not support query string parameters since it returns basic information about the database structure. We don't think there will be much demand to customize the information returned from this query. Feel free to reach out to us if that would be valuable for you.

flatfile

The flatfile endpoint supports the following query string options:

    ['sortby','order','fill_null','print_sql','version','period','frequency','component']
  1. tables: Controls which tables are returned in the query. 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. Check out the key logic section of this documentation for a discussion of the relationships between tables.
  2. 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 already contained as a primary key in another table. The fields parameters can be set to any value present in any database table.
  3. $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. When multiple field parameters are included, they form an "AND" condition rather than an "OR" condition. The only fields that cannot be specified are text fields which may contain spaces (such as station_name). Note that the dollar sign is placed in front of "field" to indicate that it is a placeholder variable for a database field. You should not actually use the word "field" as a query string parameter. A list of available fields can be found in the schema endpoint.
  4. 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.
  5. 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.
  6. 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.
  7. order: Controls whether the sortby field should be ascending (order=ASC) or descending (order=DESC). Default = ASC.
  8. period: List of natural periods for which response spectra are returned. Default is the periods used in the NGAWest2 project. Must be from the values shown in the list below.

    0.010, 0.020, 0.022, 0.025, 0.029, 0.030, 0.032, 0.035, 0.036, 0.040, 0.042, 0.044, 0.045, 0.046, 0.048, 0.050, 0.055, 0.060, 0.065, 0.067, 0.070, 0.075, 0.080, 0.085, 0.090, 0.095, 0.100, 0.110, 0.120, 0.130, 0.133, 0.140, 0.150, 0.160, 0.170, 0.180, 0.190, 0.200, 0.220, 0.240, 0.250, 0.260, 0.280, 0.290, 0.300, 0.320, 0.340, 0.350, 0.360, 0.380, 0.400, 0.420, 0.440, 0.450, 0.460, 0.480, 0.500, 0.550, 0.600, 0.650, 0.667, 0.700, 0.750, 0.800, 0.850, 0.900, 0.950, 1.000, 1.100, 1.200, 1.300, 1.400, 1.500, 1.600, 1.700, 1.800, 1.900, 2.000, 2.200, 2.400, 2.500, 2.600, 2.800, 3.000, 3.200, 3.400, 3.500, 3.600, 3.800, 4.000, 4.200, 4.400, 4.600, 4.800, 5.000, 5.500, 6.000, 6.500, 7.000, 7.500, 8.000, 8.500, 9.000, 9.500, 10.000, 11.000, 12.000, 13.000, 14.000, 15.000, 20.000
  9. frequency: List of frequencies for the fourier spectra to be returned. Default is all of the values in the list below. Must be from this list.

    0.013182570, 0.013489630, 0.013803850, 0.014125380, 0.014454400, 0.014791090, 0.015135620, 0.015488170, 0.015848932, 0.016218101, 0.016595870, 0.016982440, 0.017378010, 0.017782792, 0.018197010, 0.018620870, 0.019054604, 0.019498450, 0.019952621, 0.020417380, 0.020892960, 0.021379621, 0.021877620, 0.022387214, 0.022908680, 0.023442290, 0.023988330, 0.024547090, 0.025118870, 0.025703962, 0.026302684, 0.026915352, 0.027542291, 0.028183832, 0.028840320, 0.029512094, 0.030199520, 0.030902960, 0.031622774, 0.032359361, 0.033113110, 0.033884413, 0.034673680, 0.035481333, 0.036307800, 0.037153530, 0.038018941, 0.038904520, 0.039810720, 0.040738031, 0.041686940, 0.042657950, 0.043651580, 0.044668360, 0.045708820, 0.046773523, 0.047863020, 0.048977890, 0.050118730, 0.051286142, 0.052480750, 0.053703181, 0.054954090, 0.056234132, 0.057543992, 0.058884363, 0.060255960, 0.061659500, 0.063095730, 0.064565412, 0.066069360, 0.067608304, 0.069183100, 0.070794582, 0.072443600, 0.074131020, 0.075857751, 0.077624710, 0.079432822, 0.081283050, 0.083176370, 0.085113793, 0.087096370, 0.089125104, 0.091201100, 0.093325440, 0.095499262, 0.097723722, 0.100000000, 0.102329300, 0.104712900, 0.107151920, 0.109647820, 0.112201840, 0.114815400, 0.117489800, 0.120226430, 0.123026900, 0.125892540, 0.128824940, 0.131825700, 0.134896300, 0.138038410, 0.141253730, 0.144544000, 0.147910830, 0.151356110, 0.154881700, 0.158489310, 0.162181000, 0.165958700, 0.169824400, 0.173780100, 0.177828000, 0.181970100, 0.186208710, 0.190546100, 0.194984430, 0.199526200, 0.204173800, 0.208929610, 0.213796200, 0.218776200, 0.223872120, 0.229086800, 0.234422900, 0.239883300, 0.245470900, 0.251188600, 0.257039540, 0.263026800, 0.269153440, 0.275422900, 0.281838300, 0.288403120, 0.295120920, 0.301995200, 0.309029540, 0.316227800, 0.323593640, 0.331131100, 0.338844120, 0.346736810, 0.354813400, 0.363078100, 0.371535210, 0.380189400, 0.389045110, 0.398107140, 0.407380300, 0.416869400, 0.426579530, 0.436515800, 0.446683600, 0.457088200, 0.467735100, 0.478630100, 0.489778810, 0.501187200, 0.512861310, 0.524807500, 0.537031800, 0.549540900, 0.562341300, 0.575439920, 0.588843600, 0.602559500, 0.616594910, 0.630957300, 0.645654300, 0.660693400, 0.676083000, 0.691830930, 0.707945800, 0.724435920, 0.741310230, 0.758577600, 0.776247100, 0.794328210, 0.812830440, 0.831763700, 0.851138100, 0.870963600, 0.891250900, 0.912010800, 0.933254240, 0.954992500, 0.977237100, 1.000000000, 1.023293000, 1.047129000, 1.071519200, 1.096478000, 1.122018200, 1.148153400, 1.174897300, 1.202264100, 1.230269000, 1.258926000, 1.288250000, 1.318257000, 1.348963000, 1.380384200, 1.412537400, 1.445440000, 1.479108200, 1.513561000, 1.548816400, 1.584893000, 1.621810000, 1.659587000, 1.698244000, 1.737801000, 1.778279400, 1.819701000, 1.862087000, 1.905461000, 1.949844400, 1.995262100, 2.041738000, 2.089296000, 2.137962000, 2.187761000, 2.238721100, 2.290868000, 2.344229000, 2.398833000, 2.454709000, 2.511886300, 2.570396000, 2.630268000, 2.691535000, 2.754228300, 2.818383000, 2.884031000, 2.951209000, 3.019952000, 3.090296000, 3.162278000, 3.235937000, 3.311311000, 3.388441300, 3.467368100, 3.548134000, 3.630780000, 3.715352000, 3.801893200, 3.890451000, 3.981071000, 4.073803000, 4.168694000, 4.265795200, 4.365158000, 4.466835400, 4.570881300, 4.677351000, 4.786300100, 4.897787000, 5.011872000, 5.128613000, 5.248074000, 5.370318400, 5.495409000, 5.623413000, 5.754399200, 5.888436300, 6.025596000, 6.165949300, 6.309573000, 6.456542000, 6.606934000, 6.760828400, 6.918308200, 7.079456300, 7.244360000, 7.413103000, 7.585776000, 7.762471000, 7.943282100, 8.128304400, 8.317636400, 8.511379200, 8.709635000, 8.912507000, 9.120107000, 9.332541000, 9.549923000, 9.772372200, 10.000000000, 10.232930000, 10.471284000, 10.715192000, 10.964780000, 11.220183000, 11.481534000, 11.748973000, 12.022642000, 12.302684000, 12.589251000, 12.882492000, 13.182563000, 13.489624000, 13.803840000, 14.125370000, 14.454392000, 14.791080000, 15.135614000, 15.488170000, 15.848933000, 16.218101000, 16.595870000, 16.982440000, 17.378010000, 17.782793000, 18.197010000, 18.620870000, 19.054610000, 19.498443000, 19.952621000, 20.417380000, 20.892960000, 21.379620000, 21.877611000, 22.387210000, 22.908672000, 23.442283000, 23.988321000, 24.547080000, 25.118860000, 25.703950000, 26.302670000, 26.915340000, 27.542291000, 28.183832000, 28.840320000, 29.512094000, 30.199520000, 30.902954000, 31.622780000, 32.359363000, 33.113110000, 33.884414000, 34.673683000, 35.481334000, 36.307800000, 37.153514000, 38.018932000, 38.904510000, 39.810710000, 40.738020000, 41.686930000, 42.657940000, 43.651570000, 44.668342000, 45.708810000, 46.773500000, 47.862991000, 48.977890000, 50.118730000, 51.286144000, 52.480751000, 53.703182000, 54.954090000, 56.234130000, 57.543991000, 58.884361000, 60.255954000, 61.659500000, 63.095730000, 64.565414000, 66.069330000, 67.608283000, 69.183082000, 70.794560000, 72.443572000, 74.131004000, 75.857734000, 77.624690000, 79.432792000, 81.283030000, 83.176350000, 85.113770000, 87.096321000, 89.125100000, 91.201100000, 93.325440000, 95.499260000, 97.723724000, 100.000000000
  10. 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. This is generally OK, but potentially problematic in cases where -999 could be the actual value of a field. 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. component: Controls the ground motion components to return. Default = RotD50. Valid options for the response_spectra and intensity_measure tables include H1, H2, V, RotD0, RotD50, and RotD100. Valid options for the fourier_spectra table include H1, H2, V, and EAS.
    It is OK to specify components that are not available for a particular table. For example, if you specify "tables=response_spectra,intensity_measure,fourier_spectra&component=RotD50,EAS", you will retrieve the RotD50 component for the response_spectra and intensity_measure tables, and the EAS component for the fourier_spectra table.
    The "RotD" intensity measure components are computed from the two horizontal components by imposing coordination transformations from 0 to 180 degrees in 1 degree increments. RotD50 is the median, RotD0 is the minimum, and RotD100 is the maximum of these transformed ground motions. EAS is the Effective Amplitude Spectrum obtained by performing Konno-Omachi smoothing on the Fourier amplitude spectra for the two horizontal components, and subsequently computing the geometric mean at each frequency.