XML/JSON/CSV Help: The Example of XML link below shows the required parameters and the location parameters (coordinates or address). Likewise, we provide data-feeds in CSV and Geo-JSON. You may add additional record selection parameters as follows:
The easy way: Go to an HTML link for a dataset, e.g. pincorp-html; interactively modify your query by clicking on blue words and symbols and/or using the Criteria tab; then create the corresponding XML link by using the criteria encoded in the resulting link and add "&filetype=.xml".
The mid-easy way: Go to an HTML link for a dataset, e.g. pincorp-html; uncollapse the "More Searchable Fields" tab at the bottom of the page; it will list all fields, with field definitions and most-frequent values; click on any field to see an example of a URL querying on that field; combine multiple field queries if needed; add "&filetype=.xml"
The non-interactive way: The first record of the XML output lists field IDs and definitions of all fields. You can add criteria in the form field_id=word to restrict the field to the given value (or words in a field containing several words). It is case insensitive. For fields containing numeric data, you can also use comparison operators greater-or-equal ≥ (%3E=) and less-or-equal ≤ (%3C=). To look for a keyword in any field rather than in a specific field, specify: anyfield=keyword.
2. GeoQuery URL Interface: Detail
2.1. Submitting GeoQueries
The GeoQuery URL Interface allows users to access datasets via URL's producing query results in HTML, XML, JSON, and CSV formats.
URL Query Format:
<PATH TO ACCESS SCRIPT>?<TF ACTION LIST><LOCATION PARAMETERS><OTHER PARAMETER>
Example: The GeoQuery URL below returns all of the objects in the dataset pincorp dataset upto the default number, within the the default radius, of the specified coordinates. Please note that the XML output shows distance of every record in meters. The HTML GUI translates this into meters/km/feet/miles depending on context; but the input parameter is always in miles.
HTML: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&Lat=25.54&Long=-80.36
TFaction definitions and parameter definitions can be found in section 2.5 and 2.7. vid=nsfmod.edu identifies the user group nsfmod.edu
Locations can be defined using <LOCATION PARAMETERS> within a GeoQuery using any one of three ways.
1) Using the location's latitude and longitude coordinates. Example: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&Lat=25.54&Long=-80.36&filetype=.xml
2) Using the location's street address and zip code. Example: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&street=10700+SW+8th+street&zip=33174&filetype=.xml
3) Using the location's street address, city, and state. Example: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&street=10700+SW+8th+street&city=miami&state=fl&filetype=.xml
The GeoQuery URL Interface produces the following formats:
1) HTML - An HTML page displaying query results and an interactive TF map interface*
http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&Lat=25.54&Long=-80.36&filetype
2) XML - A standard XML file displaying query results 3) JSON - A standard Geo-JSON file displaying query results 3) CSV - A standard CSV file displaying query results *Note: In order to receive query results in HTML format, filetype
must be left blank or the parameter must be omitted altogether.
2.4. Selecting a Dataset
There are various datasets available. Users can select a dataset using the "tfaction" or "category" parameters.
tfaction=arquery<DATASET NAME>
Example:
Note:
TF actions are special parameters that allow users to specify the dataset to be displayed as well as modify the way in which it is displayed. Table 1 present a list of values allowed as TF actions.
tfaction=<REPORT WIDTH MODIFIER>
Table 1 - Report widths
|
Display Modifiers |
|
|
tabview |
displays the same fields as "shortdisplay" but html results are forced to be
tabular* |
|
shortdisplay |
displays only the main fields of the
record** |
|
longdisplay |
displays most of the fields of the
record** |
*For many datasets, tabular is the default and/or mandatory presentation.
Thus, “tabview” is not relevant for XML results.
**shortdisplay and longdisplay will yield the same results for some datasets
The general query pattern for field operators is as follows:
<SCRIPT URL><TF ACTIONS><LOCATION
PARAMETERS>arcriteria=1&<Field
Name><OP><value>&<Field Name
2><OP><value><Field Name N><OP><value>
Example:
Returns incorporated places whose name contains Pensacola OR Gulf AND whose median residents age is less than 35:
Where:
arcriteria=1& - is a separator between generic parameters (TF
Actions, Location Parameters, script location) and dataset-specific
criteria referencing the dataset's fields
<Field Name> - is the short name of a dataset field or is the
pseudo-field “anyfield”, which represents the concatenation of all
fields in the dataset.
<OP> - is an operator from the table below
<value> - any alphanumeric string. Searches are case-insensitive.
Table 2 - Available Field Operators
|
Operator |
Function |
|
= |
Equality The field contains all of the word(s) Example: 1) cityName=Key+Biscayne -- must contain both the word "Key" and the word
"Biscayne" within the cityName field. 2) anyfield=Key+Biscayne -- must contain both the word "Key" and the word
"Biscayne" independently in any field of the record. |
|
|= |
Disjunction The field contains at least one of the word(s) Example: cityName|=Miami+Chicago+Detroit Returns true for any cityName that contains
Miami, Chicago, or Detroit. |
|
!= |
Negation -does not contain the word |
|
>= |
Greater than or equal* |
|
<= |
Less than or equal * |
|
> |
Greater than* |
|
< |
Less than* |
|
|
*do not work with anyfield queries |
Logic for inequality operators:
If both operands are numerals, the comparison is numeric; otherwise
the comparison is lexicographic case-insensitive; ""<9<A=a
Example:
Returns incorporated places with populations less than or equal to 60,000: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&Lat=25.54&Long=-80.36&filetype=.xml&arcriteria=1&pop100<=60000
Returns incorporated places whose name contains Pensacola OR Gulf AND whose median residents age is less than 35:
Returns incorporated places whose name does NOT contain Pensacola AND whose population is over 60,000: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&Lat=25.54&Long=-80.36&filetype=.xml&arcriteria=1&sname!=Pensacola&pop100>=60000
Returns auto service businesses with street numbers between 300 and 37000 and that contain SHELL in their name: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerynv_autosvc&Lat=25.54&Long=-80.36&arcriteria=1&POI_ST_NUM>=300&POI_ST_NUM<=37000&POI_NAME=SHELL&anyfield=st&filetype=.xml
The GeoQuery URL interface passes parameters to backend systems. The available parameters depend on the dataset being queried. Not all parameters are modifiable or usable for all datasets.
Below you will find two tables; Table 3 contains standard parameters that are used for all datasets, and Table 4 contains modifier parameters that only work for certain datasets.
GeoQuery Format:
<PATH TO ACCESS SCRIPT>?<TF ACTION LIST><parameters other than the dataset's fields>arcriteria=1&<parameters searching dataset's fields>
Example:
Returns incorporated places whose name contains Pensacola OR Gulf AND whose median residents age is less than 35: http://vn4.cs.fiu.edu/cgi-bin/gnis.cgi?vid=nsfmod.edu&tfaction=arquerypincorp&tfaction=longdisplay&Lat=25.54&Long=-80.36&filetype=.xml&arcriteria=1&sname|=Pensacola+Gulf&sf1P013001<35
Table 3 - Standard Parameters
|
Standard Parameter |
Usage and Description |
|
|
|
|
<Field Name> |
Usage: <Field
Name><OP><VALUE> Description: A generic name given to concrete field names on a
dataset-by-dataset basis. Users can use the <Field Name> and return
results based on the operator <OP> and the <VALUE> being applied
to that particular <Field Name> In the example below
sname plays the role of <Field Name. Example: The example
below returns all incorporated place whose “sname”
field is contains
the string “Pensacola”. *See Section 1.6 for more examples |
|
place_name |
Usage: place_name Description: Allows users to
assign a label to the location being queried. Only usable when presenting
results in HTML format Example: The name of the
queried location is assigned as “My Favorite Place” |
|
vid |
Usage: vid Description: This is the id that has been assigned to you for authentication. |
|
lat |
Usage: lat=<
LATITUDE>; A valid
Latitude value is -90 to 90. Description: The latitude of
the queried location. |
|
long |
Usage: long=<
LONGITUDE> A valid
Longitude value is -180 to 180 Description: The longitude
of the queried location. |
Table 4 - Modifier Parameters
Special Constant for Searching NULL values:
There is a special, case-insensitive constant “_null” used to search for NULL values in dataset fields. When the field is known by the system to be of type numeric, then zero values are assumed to be equivalent to “_null”.
Example:
Returns objects where the value of the field areawatr is null (i.e. the field is empty or the numeric field has the value 0):
Number-of-records: How many records are returned by the query?
A: There is a default that can be overwritten with "numfind=..."
Limiting-Radius: How do we limit radius of the records to be retrieved?
A: The default radius is normally infinite -- we retrieve a limited number of matching records nearest to the given point, even if the nearest matching record is on another continent. This, however, can be user-constrained to a radius using the "d=" parameter.
Radius: What is the geographic radius within which records a returned by a query?
A: The semantics of a GeoQuery is "for a given point and criteria, get the records complying with the criteria and sorted by distance to the point". The user can override defaults for the maximum number of records to return (numfind=) and maximum distance (d=). d=Radius.
Metadata: What is the meaning and format of each field in the dataset?
A: The datafeed portal page is subdivided into sections headed by the dataset title. The first link under every such title is to the metadata, including descriptions of all columns.
Distance+Offset: What are the offset and compass directions columns?
A: The distance, offset and compass direction attributes are computed in real time, calculated by the difference between the record's latitude and longitude, and the query (URL) latitude and longitude:
| lat | Latitude of the location of this object |
| lon | Longitude of the location of this object |
| distance | Distance in meters of the location of this object from the reference point |
| compass_direction | Compass direction (N W E S NW NE SW SE) towards the location of this object from the reference point |
| offset | Normally not computed, but may be computed as the angular difference in degrees between the approximate discrete compass_direction and the exact numeric compass direction |
Search-nearby: Does GeoQuery returns the records of the nearby areas if there is no data at the given coordinates?
A: Yes
Coordinates-in-XML: Where in XML files do I find coordinates of the resultant records?
A: In fields “lat” and “lon” at the end of the record.
© 2024 Naphtali Rishe