GSAC provides a client program to make site and file queries of any GSAC repository, and get the results
returned in a variety of formats. The client uses the GSAC RESTful web API (application interface).
You can do programmatic searches of a GSAC repository, and download files.
To run the GSAC client you need Java 1.6 or higher. If needed, install Java on your machine.
To install Java on Mac, see the instructions above under "Installing GSAC."
Download
The GSAC command line client is available for download as part of the GSAC package at SourceForge.
Download the GSAC client code from SourceForge. On http://sourceforge.net/projects/gsac/
click "Download gsacclient.zip." The file is 4 MB.
Once downloaded, simply unzip the file gsacclient.zip (Linux):
unzip gsacclient.zip
This will create a directory (folder) called gsacclient, which includes, among other items, the file
gsacclient.sh and the file gsacclient/lib/gsacclient.jar.
Running
The client program is the Java archive file gsacclient/lib/gsacclient.jar. You can run the GSAC client
on LINUX or Mac with either the shell file, gsacclient.sh:
cd gsacclient/
gsacclient.sh
or directly using Java and the jar file:
java -jar gsacclient/lib/gsacclient.jar
You first may need to change file permissions; for example, by:
chmod 744 gsacclient/gsacclient.sh
The examples shown here below should work if you try them in your terminal.
On Windows, since the gsacclient is a command line tool, it must be run from a terminal. In Windows,
the terminal is the Command Prompt application. Click on Start, and then Run, and in the Run window
type cmd, and click on OK to bring up a DOS emulation window where you can enter command lines.
The client uses its own arguments and the GSAC API arguments. To see the client's command line arguments do:
gsacclient.sh -help
which shows
-properties
-server http://examplegsacrepository.edu/someprefixpath, e.g. http://facility.unavco.org/gsacws
-info fetch and print to stdout the remote GSAC repository's information, including available arguments
-download Do a file search and download the files to the given directory
-keep_paths When doing the download, do we maintain the directory structure of the ftp urls? Default is true
-query site or -site means do a site query (and add other arguments).
-query file or -file means do a file query (and add other arguments).
-out Write the output to the specified file
-output specify the format of the query results (such as 'site.xmllog' or 'file.url' )
-url act like wget
After above gsaclient arguments you can add any number of query arguments,
e.g.:
-site.code P12*
-bbox west-longi south-lati east-longi north-lati, such as bbox -120.0 30.5 -117.0 33.0
Note: for any of the arguments you can specify a file that contains extra arguments, e.g.:
-site.code file:site_queries.txt
where sites_queries.txt contains site query codes and values, one per line.
The -server argument is essential to query a remote GSAC-enabled repository.
Use the Base URL shown in the GSAC'S site Information page.
Site searches
A sample query for one GPS site is:
gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE1
Spaces separate arguments in the gsacclient command line.
The results are sent to your terminal, from the remore GSAC web services, in csv format:
#site.id,site.code,site.name,site.latitude,site.longitude,site.elevation
23478_ADE1_5650,ADE1,Australia NGA collocated,-34.729,138.6473,38.1548
The results on screen begin with the URL API, which is equivalent to the gsacclient query, in this case (one line):
http://facility.unavco.org/gsacws/gsacapi/site/search site.code=ADE1&output=site.csv
You can try this API query request in a browser. Note that "&" is the glue to connect different
arguments in the URL query. This is typical use of "&" in web services.
You can get results in other formats using the argument "-output,", such has much more information
in SOPAC XML Site Log format:
gsacclient.sh -server http://facility.unavco.org/gsacws -site.code "ADE1" -output site.xmllog
Results of this query are not shown here since they are too long.
This command
gsacclient/gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE*
finds three sites, all beginning with "ADE" (a wild card search).
That command, plus -output site.xmllog will send three SOPAC XML Site Logs.
You can direct results, such as all those site logs in XML, to a file:
gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE* -output site.xmllog -out ADE_site_logs.xml
The argument for a latitude-longitude bounding box search is
-site -bbox -120.0 30.5 -117.0 33.0
The bbox values are longitudes and latitudes: west, south, east, and north. bbox is preceeded by -site.
GSAC Client Properties File
You can specify one or more gsacclient arguments to use when running the client.
Just edit the gsac.properties file in the gsacclient/ directory. For example, uncomment the line:
server=http://facility.unavco.org/gsacws
to query the UNAVCO GSAC with every gsacclient call. To make every command a site query, add the line
query=site
You can also create and use several different properties files of the same format. For example:
gsacclient.sh -properties gsac_client_3.properties.
Any gsacclient arguments may be entered in a properties file. For example, if you want to get
more than the default 1000 results, add -limit , e.g.:
gsacclient.sh -site -limit 1500
File searches
Site code search that gets files for site P123 (caution, this returns 1001 file names).
gsacclient.sh -file -site.code p123
Results in this case are a list of information about all files available from site P123,
like this, not data files' contents:
3233505,GNSS RINEX Observation (Hatanaka, Unix Compressed),739030c019ab4169acc66a317daead0a,638221,2007-03-06,ftp://data-out.unavco.org/pub/rinex/obs/2007/064/p1230640.07d.Z
3258729,GNSS Navigation,74787c121b5fb8344240ee05c3927a33,32805,2007-02-15,ftp://data-out.unavco.org/pub/rinex/nav/2006/279/p1232790.06n.Z
Other example gsacclient queries:
Absolute time range file search for p123
gsacclient.sh -file site.code p123 -file.datadate.from 2010-09-01 -file.datadate.to 2010-09-15
which gets back 46 files.
Absolute time range file search for p123, and return FTP URLs for data files:
gsacclient.sh -file site.code p123 -file.datadate.from 2010-09-01 -file.datadate.to 2010-09-15 -output file.url
Time relative file search for p123
gsacclient.sh -file site.code p123 -file.datadate.from "-1 month" -file.datadate.to now
Both the 'from' and 'to' arguments must be used together. You can also use -file.datadate.to "-1 month".
Search on file type, for example, just get RINEX and HATANAKA files
gsacclient.sh -file -output url site.code p123 -file.datadate.from 2010-09-01 -file.datadate.to 2010-09-15 -file.type 4 -file.type 5
Type "4" is the RINEX obs file type at UNAVCO, and "5" is Hatanaka compressed obs files. met files are and nav files are .
File searches with downloads
This query will do a file query, retrieve the file FTP URLs and download the files into the
destination_directory. There is a limit of 10 download files.
gsacclient.sh -download destination_directory -site.code p123 -limit 10
This command maintains the original directory FTP file paths, on the remote GSAC server.
For example if your local destination directory is data-dir/, you may see the data files
in a path such as data-dir/pub/rinex/obs/. To have all of the files put into a single directory,
set the the -keep_paths argument to false:
gsacclient.sh -download destination_directory -site.code p123 -limit 10 -keep_paths false
Listing Repository Information
You can get information (including gsacclient arguments) about a GSAC repository with for example
gsacclient.sh -server http://facility.unavco.org/gsacws -info
Similar and more complete information is on the GSAC repository's Information page; click on
Repository information xml. That list will also show allowed values for enumerated fields in the GSAC database.
Using Linux
You can use gsac client calls as part of Linux commands, such as
gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE* -output site.xmllog | grep receiverType
lists the reciver types for sites beginning with ADE.
Then write results in a new file ADE_receiver_list:
gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE* -output site.xmllog | grep receiverType >> ADE_receiver_list