Previous Next

The GSAC Client Program

There is a GSAC client program (gsacclient.jar) for programmatic searches of a GSAC repository and to download files. The GSAC client is available as part of the GSAC package. This program is an alternative on Windows for the use of 'curl' commands on Linux, and the client may be run on Linux as well as Windows.

First review sections 3 and 4 about the GSAC API for basic concepts and API information.

The GSAC client makes site and file queries of any GSAC repository, and gets the results returned in a variety of formats. The client uses the GSAC RESTful web API (application interface). You run the GSAC client program on your own terminal's command line to do programmatic searches of a GSAC repository, and download files. In some cases this is more efficient than using the web page search forms.

To run the GSAC client you need Java 1.6 or higher. If needed, install Java on your machine.

5.1 Download the Client

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 about 4 MB.

Once downloaded, simply unzip the file gsacclient.zip (Linux):

unzip gsacclient.zip

Archive: gsacclient.zip

creating: gsacclient/

creating: gsacclient/lib/

inflating: gsacclient/lib/gsacclient.jar

inflating: gsacclient/gsacclient.sh

inflating: gsacclient/README

inflating: gsacclient/gsac.properties



This will create a directory (folder) called gsacclient, which includes, among other items, the file gsacclient.sh and the Java file gsacclient/lib/gsacclient.jar, which is the executable client. Since it is in Java it should run on any platform with Java 1.6.

5.2 Running the Client

The client program is the Java archive file gsacclient/lib/gsacclient.jar. You can run the GSAC client on LINUX or Mac using either the shell file, gsacclient.sh:

cd gsacclient/
gsacclient.sh <arguments> 

or directly using Java and the jar file:

java -jar gsacclient/lib/gsacclient.jar <arguments>

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 the terminal, running the "jar" file. 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 the GSAC API arguments and also its own arguments. To see the client's command line arguments run the client with -help, such as

gsacclient.sh -help
which shows
	-properties <properties file to load> 
	-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 <destination directory> Do a file search and download the files to 
		the given directory 
	-keep_paths <true|false> 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 <outputfile>  Write the output to the specified file 
	-output  specify the format of the query results (such as 'site.xmllog' or 
		'file.url' ) 
	-url <url to fetch> <optional filename to write to> 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.  For the server address of a particular GSAC installation, use the Base URL shown in the GSAC'S site Information page.   

5.3 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.

5.4 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.  Do not have a "/" at the end of the server URL.
The results are sent to your terminal, from the remote GSAC web service, in the short csv format with header line:
http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=ADE1&out put=site.csv 
#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 sent to your screen begin with a line ("http...") showing the GSAC URL which is equivalent to the gsacclient query, in this case:


http://facility.unavco.org/gsacws/gsacapi/site/search?site.code=ADE1&output=site.csv


This helps to learn or demo use of the GSAC API in browser requests. You can try this URL query request in a browser. Note that "&" is the glue to connect different arguments in the URL query, and "?" begins the arguments after the address. This is typical use of "&" and "?" in web services. No spaces are used.

You can get results in other formats using the argument "-output,", such as SOPAC XML Site Log format:

gsacclient/gsacclient.sh -server http://facility.unavco.org/gsacws -site.code "ADE1" -output site.xmllog

All the possible choices of formats of results from site queries are listed in the GSAC'S site Information page, in the Output Types -> Site Outputs URL section. For example, for HTML (web page) output use site.html; XML Site Log (SOPAC) output=site.xmllog; SINEX output=site.snx; GAMIT station.info output=site.station.info; csv file output=site.csv; and plain text output=site.plaintext.

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 to your terminal.

You can direct any gsacclient results, such as all those site logs in XML format, to a file:

gsacclient/gsacclient.sh -server http://facility.unavco.org/gsacws -site.code ADE* -output site.xmllog -out ADE_site_logs.xml

The command argument format for a latitude-longitude bounding box search i,s for example:

-site -bbox -120.0 30.5 -117.0 33.0

The 'bbox' values are longitudes and latitudes: the most westerly, the most southerly, the most easterly, and the most northerly. Be sure to note that bbox is preceded by -site.

5.5 GSAC Client Properties File

You can specify one or more gsacclient arguments to always use when running the client. Just edit the gsac.properties file in the gsacclient/ directory. For example, use 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 (in the same format). For example:

gsacclient.sh -properties  gsac_client_3.properties.

Will do queries using the arguments in 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 <count>, e.g.:

gsacclient.sh  -site -limit 1500

5.6 File searches

A site.code search to get all the 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 file 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 date 'from' and 'to' arguments must be used together. You could use

-file.datadate.to "-1 month".

You can search on file type; for example, to get RINEX obs files :

gsacclient.sh -file -output url site.code p123 
              -file.datadate.from 2010-09-01 
              -file.datadate.to 2010-09-15 
              -file.type gnss.data.rinex.observation

File type choices for a particular GSAC repository are listed in the GSAC'S site Information page, in the File Query -> File Type section. Click on the [+] before "Enumeration values," if there is one.

File Output formats are also selectable, and listed in the GSAC'S site Information page, in the Output Types -> File Outputs section. This choice can get information about a file, in several formats, or download the file itself (-output file.download). You can also find FTP URLs and wget scripts.

5.7 File Downloads with the GSAC Client

This query will do a file query and download some files into destination_directory. You need first to make the directory destination_directory. There is a limit of four files in this command. Some sites ahve hundreds of files so be sure to use the "limit" option.

gsacclient.sh -file -download destination_directory  -site.code p123  -limit 4

That gsacclient.sh command maintains the original directory file paths from the remote GSAC server, and cretes the same path on your machine. For example if your local destination directory is data-dir/, you may find the data files in a path such as data-dir/pub/rinex/obs/, where the /pub/rinex/obs/ part mimics the full FTP directory path to the files on the remote GSAC repository. In GSAC client terminology, this is argument

"-keep_paths true."

To have all of the files dowmloaded into a single directory, set the the -keep_paths argument to false:

gsacclient.sh  -file -download destination_directory  

-site.code p123 -limit 4 -keep_paths false


To search for metadata about instrument data files (using the the gsac client, the web page UI, or the API)


gsacclient.sh -file site.code Palm -limit 15


you can for example specify "output" (format of result) of "file.url,"


gsacclient.sh -file site.code Palm -limit 15 output file.url


and you will get a list of URLS like this:


ftp://data-out.unavco.org/pub/rinex/obs/2012/158/palm1580.12d.Z


This is of course a URL which can be used to download a file with FTP from the given server.


As always, the gscacclient shows you first the equivalent one-line API URL:


Processing file query:

http://facility.unavco.org/gsacws/gsacapi/file/search?site.code=Palm&limit=15&output=file.url


If you use "output" of "file.wget" (using the the gsac client, the web page UI, or the API)


gsacclient.sh -file site.code Palm -limit 15 output file.wget


the result returned is one or more lines such as


wget ftp://data-out.unavco.org/pub/rinex/obs/2012/158/palm1580.12d.Z


which are wget commands to download a file with "wget" from the given server.





5.8 Using Linux with the GSAC Client

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

which lists the reciever types for sites beginning with ADE:

<gnssReceiver><equip:receiverType><![CDATA[ASHTECH Z-XII3]]></equip:receiverType>

<gnssReceiver><equip:receiverType><![CDATA[ASHTECH Z-XII3]]></equip:receiverType>

<gnssReceiver><equip:receiverType><![CDATA[TRIMBLE 5700]]></equip:receiverType>

You can 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

You can get the GSAC API (URL) for any query submitted through the GSAC client. The API URL is the first line returned from any query. See examples of GSAC client use in the section titled The GSAC Command Line Client.





Previous Next