Web API Guide - Format Specifications
What format must be used when specifying a spatial region of interest
for a search?
The Web API uses a very simple format for spatial extents. They must be
latitude or longitude
Values ,
in decimal (i.e. not degrees/minutes),
comma-separated, in the order West-East-North-South (it is because of this
ordering that spatial extents are also referred to as Bounding WENS).
Longitudes in the Western Hemisphere and latitudes south of the equator
are deemed to be negative
Values
and thus must be prefixed by a
minus sign (hyphen). Thus, the valid range for West and East extents is -180
degrees to 180 degrees, and the valid range for North and South extents
is 90 degrees to -90 degrees.
The following figures show examples of valid spatial regions of interest.
The corresponding
BoundingWENS
Value
for each example is shown below the figures:
|
51.60 |
|
| -127.29 |
|
-122.65 |
|
48.53 |
|
BoundingWENS=-127.29,-122.65,51.60,48.53
|
|
50.45 |
|
2.83 |
|
14.29 |
|
37.89 |
|
BoundingWENS=2.83,14.29,50.45,37.89
|
What format must be used when specifying a temporal range
of interest for a search?
The structure of the Web API temporal range is also very simple: the start
date/time of the range is followed by the end date/time of the range, with
a comma separating the two. The date and time for start and end points must
be specified using the ISO 8601 date format. The format is described below.
- Year ,
mois
et
jour,
hyphen-separated ,
followed by
- the letter 'T',
followed by
- heure ,
minute ,
et
secondes ,
colon-separated.
The following is an example of a valid date/time string:
1996-08-29T22:01:33
It is not necessary to specify all components of a date/time; components
may be truncated from the end of the specification, e.g. the following is
also a valid date/time:
1997-03
Thus the following is an example of a valid temporal range of interest:
TimePeriod=1996-08-29T22:01:33,1997-03
What format must be used when specifying free text for a search?
The free text
Value
of the Web API can be specified as a plain
text search string or a Boolean fielded search string.
Specify a straight forward string that will be
used to match against the search target database. The target database will
contain free text values entered by the data supplier. For example, search for
"coast line".
Boolean Fielded Search Field
The more complex Boolean fielded search string can be used to search
databases that have an organized structure that the supplier makes visible
to the Discovery Portal. This search string format includes specifying
which particular fields to search and also provides 2 Boolean operators
to specify more exactly what is desired. The format of the search
string is (note: there are no spaces in this format):
( FGDC tag 1 ) : ( Free text 1 )
[and optionally ( operator 1 ) ( FGDC tag 2 ) :
( Free text 2 )
[and optionally ( operator 2 ) ( FGDC tag 3 ) :
( Free text 3 )]]
where:
- ( FGDC tag n ) is the FGDC number for a search on a particular FGDC
field. (e.g. 3124 for Theme Keyword)
- ( operator n ) is " (A) "
for and " (O) "
for or " (N) "
for and not
- ( Free text n ) is any free text including wildcards, but excluding the
operator strings (A), (O), (N) .
The expression is evaluated from right to left. This means
A AND/OR/ANDNOT B AND/OR/ANDNOT C
is always evaluated as:
((A AND/OR/ANDNOT B) AND/OR/ANDNOT C)
The following is an example of a valid Boolean fielded search string:
FreeText=1035:biodiversity(O)3124:ice
In this example, the free text request searches for all entries that
have biodiversity anywhere in the description or have the word ice in
the theme keyword.
For a complete list of FGDC search field numbers, see the FGDC
GEO Profile 2.2
For searches of organizations, services, and product collections only, the
FreeText parameter can also be an arbitrarily complex Boolean expression in
a functional notation. The supported Boolean operators are:
AND(t1,t2,...,tn)
OR(t1,t2,...,tn)
For AND, a record is selected if all the subterms
re true for the record.
For OR, a record is selected if any of the subterms are true for the record.
For ANDNOT, a record is selected if t1 is true for the record and t2 is false.
A subterm is either a simple term or another Boolean function application.
A simple term is a tag/value pair identical to those used in the Boolean fielded search
form of the FreeText parameter, e.g.: 1035:mining.
The valid tags for each database are as follows:
| Tag ID |
Meaning |
Organization |
Services |
Product Collection |
| 4 |
Title |
NO |
NO |
YES |
| 3815 |
Edition |
NO |
NO |
YES |
| 1003 |
Originator |
NO |
NO |
YES |
| 3004 |
Source Agency |
NO |
NO |
YES |
| 62 |
Sommaire |
NO |
NO |
YES |
| 3104 |
Purpose |
NO |
NO |
YES |
| 3805 |
Presentation Form |
NO |
NO |
YES |
| 3124 |
Theme Keyword |
NO |
NO |
YES |
| 2042 |
Place Keyword |
NO |
NO |
YES |
| 3130 |
Stratum Keyword |
NO |
NO |
YES |
| 2045 |
Temporal Keyword |
NO |
NO |
YES |
| 2503 |
Entity Type Label |
NO |
NO |
YES |
| 3507 |
Attribute Label |
NO |
NO |
YES |
| 3219 |
Lineage |
NO |
NO |
YES |
| 1035 |
|
YES |
YES |
YES |
| 3124 |
Thematic Areas |
YES |
NO |
NO |
| 3125 |
Work and Product Types |
YES |
NO |
NO |
Here is a complete sample expression:
ANDNOT(AND(1035:oil,1035:gas,1035:marine),
OR(1035:biodiversity,3124:ice))
This will search for entries that have
oil,
gas ,
et
marine
anywhere in the entry but not biodiversity
anywhere or
glace
in the theme keyword.
If you are using the API Builder, any special characters in the
expression will be escaped automatically for you. If you are building
the URL by hand, be sure to escape any special characters listed in this table.
For example if you were looking for the word
"marine",
or the phrase
"geodetic survey",
the FreeText parameter would appear as follows in the URL:
FreeText=OR(1035:marine,1035:geodetic%20survey)
Commas are used to separate terms in a Boolean expression. If a comma is
part of your search phrase, then it should be escaped with a backslash,
e.g. "\,". If a backslash is part of the phrase, use "\\".
Where can I get help building Web API calls?
If help is needed in building Web API calls, there is a Discovery
Portal service that a Web API user can use to construct the necessary
HTML GET and POST requests. This service asks questions as to what request
is to be generated and all the necessary Parameters, and from this provides
the URL that may be cut-and-pasted into the users web page. The service
can be invoked at:
Web API wizard.
For more information...
Should you have further questions please contact us via E-mail at:
[email protected]
| 
