Previous Next

The API

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.

4.1 Site Queries

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.

4.1.1 Linux curl GSAC commands

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.

4.2 File Queries

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.

4.3 More Query Help

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.

4.3.1 Repository Information

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.

4.3.2 URL Argument Types

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

Latitude and longitude values are in decimal degrees in GSAC.

Previous Next