Primary navigation

PLS API for Minnesota

The Public Land Survey API (application programming interface) service provides public land survey descriptions, UTM coordinates, and some place names for point locations in Minnesota.

PLS API partially replaces the SECTIC-24K software program (which does not run on Windows 7 64-bit computers). SECTIC-24K, last revised in the 1990s, is a database of public land survey section corners of Minnesota as recorded on the most recent edition of the U.S. Geological Survey's 1:24,000-scale 7.5-minute quadrangle maps available at that time. The database attempts to best fit the section corner locations shown on the published maps, even though better real world data for the locations of the section corners might be available elsewhere.
 

Example Webpage

Technical Description of the PLS API Service

The PLS API service accepts UTM coordinates, PLS descriptions, or various types of place names as inputs and returns the location in all of the above formats. The service is accessed via an http GET command with parameters. This could be done in a browser (e.g., https://imageserver.gisdata.mn.gov/cgi-bin/pls?utmx=490000&utmy=4900000) or programmatically such as via a javascript XMLHttpRequest. The results are returned in an xml-encoded response that can be decoded to retrieve the requested information.
 

Inputs

The input location can be specified in several ways. If more than one method is used, the service will pick one, possibly in an obscure manner, so don't enter more than one type of location. Locations are entered as follows, with <value or string> indicating a parameter supplied by the requester. The key/value parameters are sent in the standard fashion, separated from the url by a "?" and from each other by "&".

  1. utmx=<UTM X coordinate>
    utmy=<UTM Y coordinate>
    The NAD83 values of the x and y UTM coordinates. Note that the PLS API service does not do NAD27 <-> NAD83 translations as SECTIC did.
     
  2. latitude=<latitude in degrees>
    longitude=<longitude in degrees>
    The latitude and longitude coordinates of the location. Note that the longitude should be negative; however, the program will correct the input since all of Minnesota has negative longitudes.
     
  3. township=<township number> (required)
    range=<range number> (required)
    direction=<direction number 1=E, 2=W> (optional, defaults to 2)
    section=<section number(1-36)> (optional)
    quarters=<Up to 6 quarterings identified by the letters A, B, C, D - example DCA> (optional, A=NE, B=NW, C=SW, D=SE)
    Public Land Survey descriptions of a location. If only a township and range are supplied, the location will be the center of the township. If a section is supplied, the location will be the center of the section. Quarterings will move the location to the center of the smallest quartering.
     
  4. county=<county name>
    The location will be near the center of the specific county, specifically the midpoint of the East/West and North/South extremes. The name supplied will be checked for an exact match, and that county will be returned if found. If not, all results will be found for which the supplied string is a substring of the county name. If only one is found, that one will be returned. If none are found, an error response will be returned. If several matching results are found, they will all be returned as strings in match records - see output results section below for details. These matching strings can then be used by the user or application to select the proper value.
     
  5. quad=<24k quad name>
    The location will be the center of the named 24K quad. See county description above for how the name is matched.
     
  6. townname=<township name>
    The location will be the center of the township named. See county description above for how the name is matched. Note that not all townships have names.

In addition to the location parameters specified above, there are several additional optional parameters. These relate to the ability of the service to return an image url to MnGeo's Geospatial Image (WMS) Service for the location picked. The following parameters are optional; by default no url will be returned.

  1. url=<none|section|township|quad>
    Determines the size of the bounding box in the returned url, or does not send a url if "none" is chosen. In some cases, the service may override the requested size in order to send something appropriate to the request. The default is "none".
     
  2. size=<size in pixels>
    The size of the returned image in pixels. If the requested area is not square, this will be the longer of the vertical or horizontal size. The default is 600.
     
  3. layer=<layer name>
    Specify the name of one of the image layers from the WMS service. Note that this is the internal name, not the title. It can be found in the GetCapabilities record or as a property in ArcMap. It can also be the string "drg" which will return USGS digital raster graphic (topographic map) data at either 24K, 100K, or 250K scales, whichever is most appropriate. The default is "mncomp" which will return what is judged to be the best general purpose data for areas across the state.
     

Output Results

Successful:  If successful, the service will return an xml record similar to the following.
Note that the url inside the <wms> tags has been shortened for readability in this documentation and is thus not valid.

<response>
    <latitude>45.00768</latitude>
    <longitude>-93.10577</longitude>
    <utmx>491665</utmx>
    <utmy>4983810</utmy>
    <township>29</township>
    <range>22</range>
    <section>7</section>
    <quarters>CCCB</quarters>
    <county>Ramsey</county>
    <quad>White Bear Lake West</quad>
    <townname>unnamed</townname>
    <wms>https://imageserver.gisdata.mn.gov/cgi-bin/wmsz?Service=WMS...bbox=482076,4970815,501254,4996804</wms>
</response>

The xml tags correspond to the same names as supplied in the input parameter listed above. All fields which were not supplied as inputs will be returned. In the case of string parameters (county, quad or township name), that field will also be returned since it may have resulted from an expanded version of a partial match of the input.
 

Errors:  In the case of errors (in this case, the point was in Iowa), the record will look like:

<response>
    <error>Point not in Minnesota</error>
    <utmx>479180</utmx>
    <utmy>4677246</utmy>
</response>

Other errors will have different text inside the <error> tag.
 

Duplicate Names:  Finally, in the case of county, township or quad names which were not unique, an xml record like the following will be returned. The request was for townname=brook and many of the matches were removed for brevity.

<response>
    <match>Bass Brook</match>
    <match>Brook Park</match>
    <match>Brooklyn Center</match>
    <match>Brookville</match>
    <match>Westbrook</match>
</response>

A new request with townname set to any of the matches will return a coordinate xml record.
 

Questions?

 

back to top