Previous | Next |
The GSAC Repository supports a RESTful web API (application interface). You compose a URL to do queries and choose a format for the results, without using the GSAC UI web page forms.
For use of the GSAC API, first see section 3.3 which introduces arguments to GSAC queries. The GSAC URL API and the GSAC client (section 5) use the same arguments.
Any API URL begins with the base URL or root path of the repository, listed in its web site Information page as the Base URL, e.g. http://facility.unavco.org/gsacws/gsacapi.
For GSAC queries you add more to the base URL, such as for a site query by "site.code" for site code P210
http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=SSIA&site.name=Ilopang__SLV2007
Enter that in a browser, which searches the UNAVCO GSAC archive for all sites with code SSIA and name Ilopang__SLV2007.
This query results in the default format for a site query, HTML, which makes a new page in the browser. For other site query result output formats you append "output=," such as
http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=P210&output=site.snx
which returns a SINEX-format file, or to return a site log in SOPAC XML Site Log format, use output=site.xmllog.
Note that the & character is glue between search name-value pairs, and quotations marks are not allowed. In a site name like for name St Helena use the string St+Helena in the URL for the site.name= search.
All terms for an GSAC API query at a particular GSAC repository are listed on its web site Information page, under Site Query for sites, and under File Query for files. File searches can also use all site selection choices. All the valid terms for return formats for site queries are listed on the web site's Information page, under Output types -> Site Outputs.
Any valid GSAC HTTP URL can be invoked from a Linux command with the Linux 'curl' utility. For example this command adds curl to a site searrch with SINEX output:
curl "http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=P210&output=site.snx"
To see if you have curl, use the command which curl, normally returning something like /usr/bin/curl.
Note that the url in a curl command is inside quotation marks " ".
Here are some more examples of site searches using Linux commands with the curl utility. )The URL in each command can be used in a browser for the same query and result.) The 'arguments' in the command follow the "?" and the "&".
The command:
curl "http://facility.unavco.org/gsacws/gsacapi/site/search/sites?output=site.snx\&site.code=P30*"
will list on your terminal a SINEX file for all GNSS stations whose code (ID) begins with "P30" (ten stations in this case).
For several distinct stations by each code(ID):
curl "http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=P123&site.code=MTWO&site.code=AB04&output=site.snx"
Or both ways, by individual names and with a search for IDs like AB0*:
curl "http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=P120&site.code=MTWO&site.code=AB0*&output=site.snx"
GSAC correctly merges the information from all stations found into one SINEX file.
To get results in GAMIT station.info format, use argument output=site.station.info:
curl "http://facility.unavco.org/gsacws/gsacapi/site/search/sites?output=site.station.info\&site.code=p123"
To make results in the "SOPAC XML log file" format, use output=site.xmllog; for JSON use output=site.json; for a CSV file use output=site.csv.full; and for a plain text for easy reading use output=site.plaintext.
To get stations inside a
latitude-longitude bounding box (region), use these spatial bounding
arguments:
bbox.north=40.0 for latitudes ≤40.0, the north side
of the box is at 40 north latitude;
bbox.south=30.0 for latitudes
≥30.0
bbox.east=-100.0 for longitudes ≤-100.0, the east side
of the box is at longitude -100 (100 west longitude or 260 east
longitude)
bbox.west=-110.0 for longitudes ≥-110.0
Longitude
is in positive degrees east.
Also you can limit the station count returned with the argument limit=[some number], such as limit=25.
For example:
curl "http://facility.unavco.org/gsacws/gsacapi/site/search/sites?output=site.station.info\&bbox.north=41.0\&bb.east=-104.0\&bb.south=37.0\&bb.west=-112.0\&limit=25"
Add "> demo_station.info" to the end of the command to put the results in a local file named demo_station.info. Lacking the limit=25, this command returns 575 lines of information in station.info format. The same search, with results in SOPAC XML site log format, returns 31736 lines.
For querying files you use an API URL beginning with the Base URL, like for site searches. File queries are very much like site queries, but begin with, for example,
curl "http://facility.unavco.org/gsacws/gsacapi/file/search?
before the API arguments.
Here is a URL to get metadata about data files in a given time range from stations in the network "COCONet" and whose sampling rate is "normal." The API choice site.interval=interval.normal is distinctive to the UNAVCO GSAC. The output format is GSAC Full CSV. The output is redirected with the Linux > to a file.
http://facility.unavco.org/gsacws/gsacapi/file/search?site.group=COCONet&output=file.csv&file.datadate.from=2013-11-01&file.datadate.to=2014-01-31&site.interval=interval.normal&limit=50000" > coconet_2013Nov-thru2014Jan_data_files_normrate_info.csv
The search is limited to 50,000 lines of file metadata. This query found information 29,942 files.
Some file queries return actual data files. Be cautions since a single GNSS file may be, say, 8 MB.
All the valid terms for a file query at a particular GSAC repository are listed on its web site Information page, under File Query. The results can be returned in a variety of output formats using the "&output=" URL term plus a value, such &output=file.zip. All the valid output arguments for return formats for file queries are listed on the web site's Information page, under Output types -> File Outputs.
In the Information page you find additional API query terms, such as in sections Misc. Arguments and Vocabularies. See section 3.
To learn more about GSAC API use, try some site and file queries with GSAC API arguments using a browser and a working GSAC repository, such as the UNAVCO GSAC Repository at http://facility.unavco.org /data/gsacws.
To get the GSAC API capabilities programatically, you can query any GSAC for its repository information. The "Repository Information" for a GSAC web site lists all of the API arguments. You can see this information in a GSAC Information page, at the Repository information xml link, or retrieve it with a command like this:
http://facility.unavco.org/gsacws/gsacapi/repository/view?output=xml
for the UNAVCO GSAC.
We have tried to be flexible with how URL arguments are used. In this section "arg" stands for one of the API's URL arguments such as "site.code."
string - There may be none, one, or more of a URL string argument:
arg=p123&arg=p456
Each argument may be a semi-colon delimited list of argument values:
arg=p123;p456
arg=p12* - find values that begin with P12 arg=*123 - find values that end with P12 arg=*12* - find values that contain P12
arg=!p123 do not show results from station P123
Also, one can specify the string search type with the <arg>.searchtype argument. This can take on the values:
<arg>.searchtype=exact <arg>.searchtype=beginswith <arg>.searchtype=endswith <arg>.searchtype=contains
enumeration - Just like the string type but without the wildcard capabilities.
boolean - A boolean argument may be undefined, "true" or "false".
date_range - There are 2 arguments that may specified: "<arg>.from" and "<arg>.to". There may be none, one or both of these. If specified the logic is:
date value ≥ arg.from date value ≤ arg.to
The date string can be any of the following forms. See here for information.
yyyy-doy - year and 3 digit day of year yyyy-MM-ddTHH:mm:ss Z yyyyMMddTHHmmss Z yyyy/MM/dd HH:mm:ss Z yyyy-MM-dd HH:mm:ss Z EEE MMM dd HH:mm:ss Z yyyy yyyy-MM-ddTHH:mm:ss yyyyMMddTHHmmss yyyy/MM/dd HH:mm:ss yyyy-MM-dd HH:mm:ss yyyy-MM-ddTHH:mm Z yyyyMMddTHHmm Z yyyy/MM/dd HH:mm Z yyyy-MM-dd HH:mm Z yyyy-MM-ddTHH:mm yyyyMMddTHHmm yyyy/MM/dd HH:mm yyyy-MM-dd HH:mm yyyy-MM-dd yyyy/MM/dd yyyyMMdd yyyy-MM yyyyMM yyyy/MM yyyy now
If a timezone is not specified then the date/time is assumed to be in UTC.
You can also specify a date value that is relative to the other date:
-1 week, +3 days, -1 month, etc.
For example, to find the last 2 weeks of data from current time you would use:
arg.from=-2 weeks&arg.to=now
If you wanted to search 3 days into the future:
arg.from=now&arg.to=+3 days
number_range - There are 2 arguments that may specified: "<arg>.min" and "<arg>.max". There may be none, one or both of these. If specified the logic is:
value ≥ arg.min value ≤ arg.max
spatial_bounds - There are 4 arguments that may specified:
<arg>.north [most northerly] <arg>.south [most southerly] <arg>.east [most easterly] <arg>.west [most westerly]
The values are assumed to be in degrees north (for latitude) and degrees east (for longitude). Not all arguments are needed. If specified the logic is:
site location latitude ≤ arg.north site location latitude ≥ arg.south site location longitude ≤ arg.east site location longitude ≥ arg.west
Latitude and longitude values are in decimal degrees in GSAC.
Previous | Next |