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.
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 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.
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 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.
To see a running output of the logs for the container, execute the following:
> docker logs -f reso-upi-service-containerTo see a snapshot of the logs for the container, execute the following:
> docker logs reso-upi-service-containerThis cleans up the docker environment:
> ./scripts/remove_container.sh The following command allows you to see the containers that are running.
> docker ps -aIf you need to log into the service container, use the following command.
> docker exec -it reso-upi-service-container /bin/bashThe 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.
The API is documented in the API Document file.
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":""}
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"}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"}]
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