Searching

Searching allows you to find information in more than 1,000,000 rows of spatial State Geographic Information Datasource (SGID) data without expensive software or licensing. With over 300 tables of real-world Utah data that you can run queries against in the SGID, the possibilities can be a little overwhelming. The search endpoint offers vast potential for data extraction. This UGRC API endpoint allows you to query geometries and attributes from any table in the Open SGID.

URI Format

HTTP GET

https://api.mapserv.utah.gov/api/v1/search/{table}/{fields}?apikey={key}

Parameters

Required path parameters

table

The schema qualified name of an Open SGID table. Read the getting connected guide to start browsing the Open SGID.

• Type: string
• Example: boundaries.county_boundaries

fields

A comma separated string of fields to return from the Open SGID table.

Tip

There are a few special tokens to access geometry data.

• shape@ provides a geometry simplified with a tolerance of 10 meters. The search endpoint is intended for map extents and general data extraction, so this geometry may not preserve every detail of the source feature. For more precise geometry or access to additional geometry features, use the feature services available in SGID on ArcGIS.
• shape@envelope provides the minimum bounding box around the geometry.

• Type: string
• Example: name,fips,shape@

Optional query string parameters

predicate

The predicate allows you to filter the result. Use simple PostgreSQL predicates.

• Type: string
• Default: 1=1
• Example: UPPER(name) like '%K'

geometry

The point, polyline, polygon, multipoint, or envelope geometry types used for spatial queries. These geometries are denoted as geometryType:ArcGIS Server JSON representation. eg:

• Type: string
• Example: point:{"x":464912.85,"y":4497772.12,"spatialReference":{"wkid":26912}}

buffer

A distance in meters to buffer the input geometry. 2000 meters is the maximum buffer.

• Type: integer
• Default: 0
• Example: 10

attributeStyle

The format the input field name keys are returned as in the result array attributes dictionary. This is useful for having consistent access to the response data keys in code.

• Type: string

• Default: lower

• Can be one of: lower, upper, input

• Example (lower):

  [{ "attributes": { "name": "SALT LAKE" } }]

• Example (upper):

  [{ "attributes": { "NAME": "SALT LAKE" } }]

• Example (input): where the fields input is Name

  [{ "attributes": { "Name": "SALT LAKE" } }]

spatialReference

The spatial reference defines how the coordinates will represent a location on the earth defined by how the round earth was made flat. The well known id’s (WKID) of different coordinate systems define if the coordinates will be stored as degrees of longitude and latitude, meters, feet, etc. This endpoint supports the WKIDs from the Geographic Coordinate System reference and the Projected Coordinate System reference. UTM Zone 12 N, with the WKID of 26912, is the default. This coordinate system is the most accurate reflection of Utah. It is recommended to use this coordinate system if length and area calculations are important as other coordinate systems will skew the truth.

• Type: number
• Default: 26912

Popular Spatial Reference Ids

WKID	NAME	REASON
26912	UTM Zone 12 N	This is the State standard for all Utah spatial data. It has the least distortion for the state of Utah and the most accurate length and area calculations.
3857	Web Mercator	This is the standard for all data displayed on a web map. Most base map services use a web mercator projection.
4326	Latitude/Longitude (WGS84)	This is the ubiquitous standard for spatial data. Many systems understand this format which makes it good for interoperability.

Reference Information

• What are map projections?
• What are projected coordinate systems?
• What are geographic coordinate systems?

format

There are three output formats for the result object. The default being empty. esrijson will parse into an esri.Graphic for mapping purposes and geojson will format as a Feature. If this value is omitted, the default json will be returned.

• Type: string
• Can be one of: esrijson, geojson

callback

The callback function to execute for cross domain javascript calls (jsonp). This API supports CORS and does not recommend the use of callback and jsonp.

• Type: string

Response Shapes

Successful Example

{
"result": [
  {
  "attributes": {
    "name": "WASATCH",
    "fips": 51
  }
  }
],
"status": 200
}

Error Example

Tip

Be sure to inspect the failed requests as they contain useful information. 401 status codes equates to your API key having problems. 404 equates to the route and milepost not being found. 200 is successful.

{
  "status": 401,
  "message": ""
}

JSON Schema

{
  "type": "object",
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "item": {
          "type": "object",
          "properties": {
            "attributes": {
              "type": "object",
              "patternProperties": {
                ".*": {
                  "type": "any"
                },
              }
            }
          }
        },
      },
      "status": {
        "type": "integer"
      }
    }
  }
}