Skip to content

mlesswing/reso-upi-service-container

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RESO UPI Service Container


Table of Contents


Introduction

This is a container-based service for the RESO UPI (Universal Property Identifier). It can create or validate a RESO UPI using a RESTful API. It can also be used to discover information about states, counties, and towns from text-based hints.

The container is preconfigured with the following properties:

Property Description Setting
host IP Address of the server "0.0.0.0"
name Used for Docker commands reso-upi-service-container
port Port serviced by the server 8081
withTLS Server is secure (HTTPS) false
 

The container is not configured to support TLS requests and is intended for internal use, not as a publically-available service.


Installation

The Docker container service must be installed on the computer that the API Service container will be installed on. There are many guides on the internet that discuss Docker installation and a good place to start would be the installation tools provided by the distributor.

The following script can be used to install the API Server as a container-based application once Docker is installed.

> ./scripts/build_container.sh 

Container Operations

Scripts located in the scripts directory of the distribution can simplify Docker use.

  • build_maintainer_container.sh
  • build_reso_container.sh
  • monitor_container.sh
  • start_container.sh
  • stop_container.sh
  • teardown_container.sh

The scripts were developed using a bash shell. Refer to the script code for details regarding Docker invocation.

Build or Rebuild the Container

Containers are built from images stored in a repository. This package is available through a RESO repository as well as a repository operated by the maintainer. The versions published by the maintainer are for development and may contain unstable versions.

This builds and starts the container from an image in the RESO repository:

> ./scripts/build_reso_container.sh 

This builds and starts the container from an image in the repository provided by the maintainer:

> ./scripts/build_maintainer_container.sh 

Starting and Stopping the Container

Once build, a container can be started with the follwing:

> ./scripts/start_container.sh 

The container can be stopped with the following:

> ./scripts/stop_container.sh 

You should only build the container once, and then use the start and stop processes to control the container.

Monitor the Container

To see a running output of the logs for the container, execute the following:

> docker logs -f reso-upi-service-container

To see a snapshot of the logs for the container, execute the following:

> docker logs reso-upi-service-container

Removing the Container

This cleans up the docker environment:

> ./scripts/remove_container.sh 

View the Container

The following command allows you to see the containers that are running.

> docker ps -a

Log into a Container

If you need to log into the service container, use the following command.

> docker exec -it reso-upi-service-container /bin/bash

API Methods

The examples in this section use scripts to perform the described operations. The scripts were developed using a bash shell and the curl command line tool.

Refer to the script code for details regarding API invocation.

API Documentation

The API is documented in the API Document file.

Build a UPI

The service can build a UPI from either six or seven pieces of information.

Both forms support an additional parameter called reference that is intended to be used for validation. It is handled as an opaque parameter that is only meaningful to the originating system; what ever is input is returned. If the originating system is an MLS, then then reference parmeter could be the ListingID.

The six element version is useful for systems that have the codes associated with the inputs. The parameters are:

API Field Example Description
country 'US' Country
fips '50013' FIPS code
subcounty '50650' County subdivision code
parcel '666777888' Parcel identifier
propertyType 'R' Property type
subproperty 'N' Subproperty
reference '9034a1f01686b32c28783e77c7114ff1383dee41ebb9f1a1aafcbacb358591d0' An opaque identifier
 

The service uses FIPS information for the U.S, from the US Census Bureau.

The seven element version of the API is designed to be used by MLS systems. Instead of using a FIPS code for state and county identifiers, a text description is used. Also, the contents of City field is used instead of the subcounty code. The parameters are:

API Field Example RESO DD Field
country 'US' Country
state 'VT' StateOrProvince
county 'Grand Isle' CountyOrParish
subcounty 'North Hero' City
parcel '666777888' ParcelNumber
propertyType 'R' Fixed
subproperty 'N' Fixed
reference '377729' ListingId
 

The service uses two letter abbreviations for states and provinces in the US, Canada, and Mexico comes from the Hierarchical administrative subdivision codes (HASC) extensions to ISO 3166. The two letter abbreviation is not unique across countires. The two letter abbreviation should always be used with the country code to gaurantee uniqueness. An example would be US-AL for Alabama or MX-MX for Estado De Mèxico. The API resuires both parameters when asking for a list of states or provinces.

The following script demonstrates building a UPI with bot sets of inputs. Each form uses the /upi/build API method:

> ./scripts/build_upi.sh
============
 RESO UPI Service

 API Method: upi/build
============

Sending to API Server at: http://localhost:8081
---
Scenario #1: Build a upi with seperate state and county
---
{"country":"US","state":"VT","county":"Grand+Isle+County","subcounty":"North+Hero","parcel":"666777888","propertyType":"R","subproperty":"N"}
{"success":true,"upi":"US-50013-50650-666777888-R-N","reference":"","confidence":"HIGH","notes":""}
---
Scenario #2: Build a upi with seperate state and county and no subcounty
---
{"country":"US","state":"VT","county":"Grand+Isle+County","subcounty":"00000","parcel":"666777888","propertyType":"R","subproperty":"N"}
{"success":true,"upi":"US-50013-00000-666777888-R-N","reference":"","confidence":"LOW","notes":"There are 5 subcounties in this county and none were specified in the request"}
---
Scenario #3: Build a upi with seperate state and county and no subcounty where subcounty exists
---
{"country":"US","state":"CA","county":"San+Francisco","subcounty":"00000","parcel":"5843020","propertyType":"R","subproperty":"N"}
{"success":true,"upi":"US-06075-92790-5843020-R-N","reference":"","confidence":"MEDIUM","notes":"The subcounty was not specified, but is being overriden with the county default [San Francisco CCD]."}
---
Scenario #4: Build a upi with fips using API short form
---
{"success":true,"upi":"US-50013-50650-666777888-R-N","reference":"","confidence":"HIGH","notes":""}
---
Scenario #5: Build a upi with seperate state and county and a reference
---
{"country":"US","state":"VT","county":"Grand+Isle+County","subcounty":"North+Hero","parcel":"666777888","propertyType":"R","subproperty":"N","reference":"listingid001"}
{"success":true,"upi":"US-50013-50650-666777888-R-N","reference":"listingid001","confidence":"HIGH","notes":""}

Parse a UPI

The following script demonstrates parsing a UPI with the /upi/parse method.

./scripts/parse_upi.sh 
============
 RESO UPI Service

 API Method: upi/parse
============

Sending to API Server at: http://localhost:8081
---
Scenario #1: parse a upi
---
Parcing UPI US-50013-50650-666777888-R-N
{"county_code":"013","county_name":"Grand Isle County","country_code":"US","country_name":"United States","fips":"50013","parcel":"666777888","property_type":"Real Property","property_type_code":"R","state_abbreviation":"VT","state_code":"50","state_name":"Vermont","subcounty_code":"50650","subcounty_name":"North Hero town","subproperty_code":"N","subproperty_name":"N/A","upi":"US-50013-50650-666777888-R-N"}

Discover UPI Information

The Discover capability can be useful when constructing parameters for building UPIs because it creates codes that can be used to build UPIs.

If you use the name of an area (such as a county or town) to discover UPI information, the service will look for matches across all states, counties, and subcounties. Each result contains codes that can be used to build a UPI. Only one of the results si what you were looking for.

The structure of each hint includes fields for the country_code, fips_code, and subcountry_code of the candidate hint. Here is an example of one of the hints received when searching for "Kane".

{
...
{"country_code":"US","fips_code":"17089","subcounty_code":"60365","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Plato township"},
...
}

The country_code, fips_code, and subcountry_code for the hint is received as well as a field named 'hint_descriotion`. The hint_descriotion indicates that the match "Kane" occurred on the county level. The system matched the stored county name of "Kane County".

The following script demonstrates discovering UPI information with the /upi/discover method.

./scripts/discover.sh                 
============
 RESO UPI Service

 API Method: upi/discover
============

Sending to API Server at: http://localhost:8081
---
Scenario #1: Return geographic hints API Server
---
Retreiving hints for: Kane
[{"country_code":"US","fips_code":"17061","subcounty_code":"38882","hint_description":"Level=Subcounty, State=IL, County=Greene County, Subcounty=Kane township"},{"country_code":"US","fips_code":"17089","subcounty_code":"03025","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Aurora township"},{"country_code":"US","fips_code":"17089","subcounty_code":"04091","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Batavia township"},{"country_code":"US","fips_code":"17089","subcounty_code":"05989","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Big Rock township"},{"country_code":"US","fips_code":"17089","subcounty_code":"06262","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Blackberry township"},{"country_code":"US","fips_code":"17089","subcounty_code":"09772","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Burlington township"},{"country_code":"US","fips_code":"17089","subcounty_code":"10903","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Campton township"},{"country_code":"US","fips_code":"17089","subcounty_code":"21046","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Dundee township"},{"country_code":"US","fips_code":"17089","subcounty_code":"23087","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Elgin township"},{"country_code":"US","fips_code":"17089","subcounty_code":"28885","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Geneva township"},{"country_code":"US","fips_code":"17089","subcounty_code":"32538","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Hampshire township"},{"country_code":"US","fips_code":"17089","subcounty_code":"38908","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Kaneville township"},{"country_code":"US","fips_code":"17089","subcounty_code":"38908","hint_description":"Level=Subcounty, State=IL, County=Kane County, Subcounty=Kaneville township"},{"country_code":"US","fips_code":"17089","subcounty_code":"60365","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Plato township"},{"country_code":"US","fips_code":"17089","subcounty_code":"66430","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Rutland township"},{"country_code":"US","fips_code":"17089","subcounty_code":"66716","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=St. Charles township"},{"country_code":"US","fips_code":"17089","subcounty_code":"73404","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Sugar Grove township"},{"country_code":"US","fips_code":"17089","subcounty_code":"78188","hint_description":"Level=County, State=IL, County=Kane County, Subcounty=Virgil township"},{"country_code":"US","fips_code":"19011","subcounty_code":"92289","hint_description":"Level=Subcounty, State=IA, County=Benton County, Subcounty=Kane township"},{"country_code":"US","fips_code":"19155","subcounty_code":"92292","hint_description":"Level=Subcounty, State=IA, County=Pottawattamie County, Subcounty=Kane township"},{"country_code":"US","fips_code":"27069","subcounty_code":"60646","hint_description":"Level=Subcounty, State=MN, County=Kittson County, Subcounty=Skane township"},{"country_code":"US","fips_code":"36067","subcounty_code":"67521","hint_description":"Level=Subcounty, State=NY, County=Onondaga County, Subcounty=Skaneateles town"},{"country_code":"US","fips_code":"38009","subcounty_code":"41300","hint_description":"Level=Subcounty, State=ND, County=Bottineau County, Subcounty=Kane township"},{"country_code":"US","fips_code":"42083","subcounty_code":"38688","hint_description":"Level=Subcounty, State=PA, County=McKean County, Subcounty=Kane borough"},{"country_code":"US","fips_code":"49025","subcounty_code":"91591","hint_description":"Level=County, State=UT, County=Kane County, Subcounty=Kanab CCD"},{"country_code":"US","fips_code":"49025","subcounty_code":"92494","hint_description":"Level=County, State=UT, County=Kane County, Subcounty=Orderville CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"90048","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Airway Heights CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"90056","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Amber-Cheney South CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"90552","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Cheney-Medical Lake CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"90640","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Colbert CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"90880","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Deer Park CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"91616","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Liberty Lake CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"92080","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Mount Spokane CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"92080","hint_description":"Level=Subcounty, State=WA, County=Spokane County, Subcounty=Mount Spokane CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"92816","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Rockford CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"93200","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Spokane CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"93200","hint_description":"Level=Subcounty, State=WA, County=Spokane County, Subcounty=Spokane CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"93224","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Spokane South CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"93224","hint_description":"Level=Subcounty, State=WA, County=Spokane County, Subcounty=Spokane South CCD"},{"country_code":"US","fips_code":"53063","subcounty_code":"93584","hint_description":"Level=County, State=WA, County=Spokane County, Subcounty=Valleyford CCD"},{"country_code":"US","fips_code":"53065","subcounty_code":"93216","hint_description":"Level=Subcounty, State=WA, County=Stevens County, Subcounty=Spokane Reservation CCD"}]

---
Scenario #2: Return geographic hints API Server
---
Retreiving hints for: Charleston
[{"country_code":"US","fips_code":"17029","subcounty_code":"12580","hint_description":"Level=Subcounty, State=IL, County=Coles County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"19111","subcounty_code":"90647","hint_description":"Level=Subcounty, State=IA, County=Lee County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"20201","subcounty_code":"12625","hint_description":"Level=Subcounty, State=KS, County=Washington County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"23019","subcounty_code":"12105","hint_description":"Level=Subcounty, State=ME, County=Penobscot County, Subcounty=Charleston town"},{"country_code":"US","fips_code":"26077","subcounty_code":"14720","hint_description":"Level=Subcounty, State=MI, County=Kalamazoo County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"36057","subcounty_code":"13816","hint_description":"Level=Subcounty, State=NY, County=Montgomery County, Subcounty=Charleston town"},{"country_code":"US","fips_code":"37173","subcounty_code":"90624","hint_description":"Level=Subcounty, State=NC, County=Swain County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"42117","subcounty_code":"12728","hint_description":"Level=Subcounty, State=PA, County=Tioga County, Subcounty=Charleston township"},{"country_code":"US","fips_code":"45019","subcounty_code":"90570","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Charleston Central CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"90570","hint_description":"Level=Subcounty, State=SC, County=Charleston County, Subcounty=Charleston Central CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"90988","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Edisto Island CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"91664","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=James Island CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"91703","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Johns Island CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"91761","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Kiawah Island-Seabrook Island CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"92080","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=McClellanville CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"92301","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Mount Pleasant CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"92424","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=North Charleston CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"92424","hint_description":"Level=Subcounty, State=SC, County=Charleston County, Subcounty=North Charleston CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"92771","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Ravenel-Hollywood CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"93549","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=Wadmalaw Island CCD"},{"country_code":"US","fips_code":"45019","subcounty_code":"93646","hint_description":"Level=County, State=SC, County=Charleston County, Subcounty=West Ashley CCD"},{"country_code":"US","fips_code":"50019","subcounty_code":"13150","hint_description":"Level=Subcounty, State=VT, County=Orleans County, Subcounty=Charleston town"}]

Get Build Version

Execute the following script to return all facts.

> ./scripts/getServerVersion.sh
============
 RESO UPI Service

 API Method: version
============

Sending to API Server at: http://localhost:8081
---
Scenario #1: Return the build version of the API Server
---
Version: build20210317

Notes


About

A public version of a RESO UPI Service container.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published