REACH F Your appgrand prisubmissiplans.  ThMonmouongoing  ScalabilitScalabilitState of N

a. Pb. If

stca

c. ExSyd

d. Ifst

Please lim

 Qbase’s regions requireminclude: 

inal Submiss

p’s scalabilityize.  The judons.   To judhis form is youth County, use. 

tyty refers to hNew Jersey. lease explaif your app hatrategy for aapabilities oxplain how yystems (HMifferent platf you do not trategy you 

 mit your res

application, beyond  Red

ments. We cu

A databa

An automincludingenhance,

sion – Scala

y, sustainabiges will evaldge scalabilitour opportuNew Jersey 

how well, ho  n how muchas plans to sachieving thaf your app wyour app wilIS) across thtforms. plan to use use. 

sponse to 1,

Homeless REd  Bank,  NJ. urrently serve

se containing

mated Extract:  flat  files,  d and update t

bility and Su

lity, compleluate complety and sustaiunity to explaand then pe

ow quickly, a

h of the counerve more gat scale, inclwill not be scl interact wihe country at

HMIS datab

500 words.

Figure 1: Pro

EACH, was orOur  platform

e the entire U

g over 110,00

t, Transform,ata warehouthe database

ustainability

teness, and eteness andnability, howain how welersists as a fr

and how com

ntry your apgeographiesuding how qcaled up. ith the Homet local Conti

ases for she

oject REACH Arc

riginally desigm  is  flexibleUnited States 

0 services acr

, and  Load  (Euse  sites,  and on an hourly

y 

user experie user experiwever, we wl and how qree service t

mpletely you

p serves todafter the coquickly it wil

elessness Mnuums of Ca

elter bed ava

hitecture 

gned as a plae  and  can  band our scala

ross the coun

ETL) process d  standard wy or daily basi

ence will detence when t

will need youuickly your ao people acr

ur app serves

day.   ompetition, pl occur and w

Management are that use 

ailability, ple

atform  to supbe  scaled  toability featur

ntry. 

that accessewebsites  to  cis. 

termine if it testing youru to summarapp scales bross the cou

s people bey

please explawhether any

Informationsystems run

ease describe

pport geograo  meet  new es and capab

es over 12  socontinuously 

wins the r final rize your eyond untry for 

yond the 

ain your y 

n nning on 

e the 

 

phical data 

bilities 

ources mine, 

  

2

Job Search capability queries and aggregates jobs from over five unique sources including: NRD, CareerBuilder, Indeed, and SimplyHired. 

The application allows a user to search for information from anywhere in the United States with two search options:  

o Search based on current device location. o Search by entering a complete or partial address (such as city and state or zip code) 

for services near designated location. 

The  application  gives  the  user  the  ability  to  “bookmark”  a  shelter  and  receive  “push notifications” regarding availability on any or all of the user’s devices (Android or iOS). 

The ability to add,  update, and capture new data on places from our website including the ability to capture descriptions of intake processes and key contacts for reserving beds at a specific shelter 

 The Homeless REACH database currently contains over 110,000 services across the country. This data has come from a variety of websites and sources. An automated process in our platform continuously mines,  enhances,  and  updates  our  database  on  a  daily  or  hourly  basis  depending  on  the  data  and source.  At  present  current  data  categories  includes:  Shelters,  Food  Banks,  Hospitals,  VA  Facilities, transportation, legal assistance, job assistance, and jobs for the entire United States.  An advantage of our ETL process  is  the easy addition of new data and  service  types without major modifications  to  the  Homeless  REACH  application  itself.  This  allows  for  the  addition  of  more information and service types if a new need should arise.    As an example, during our First Beta Test in Red Bank, NJ, we received feedback from The Soul Kitchen and  the volunteers at  Lunch Break and Monmouth Resource Center. They  suggested other areas of data  that we  should  capture  to make  the Homeless  REACH  application more  complete  and  useful. Based  on  that  feedback we  added  new  data  sources  for:  Employment  Assistance  resources, Utility Assistance, and more hotline information to our database. We were able to do so without needing to change  our  application  platform  and  only  had  to  identify  the  data  sources  and  create  new  ETL processes.  Assistance  Services was  a  new  service  type  and,  as  such,  required  a  new  screen  to  the applications to display this new service type information.  Homeless Information Management Systems (HMIS)  We recognize that HMIS is the ideal place to collect information and recommend it be the standard for managing  and  disseminating  bed  count  information.    Our  Homeless  REACH  platform  is  capable  of supporting the HUD XML Schema Definition for HMIS Data, version 3.0.   After discussions with groups  in Los Angeles, CA, and the Arlington, VA Continuum of Care (CoC) who support the homeless and veteran communities, we recognize that access to HMIS  information  is not easy for a third party entity and requires the support of larger entities, such as the VA or HUD, to make this data available to the public.   One specific reason we were given for not being able to access the data directly as a  third party public application  is  the data  that  is  collected within  the HMIS  system contains Personal Identifiable Information.  With access to the local HMIS system, our Homeless REACH platform  can  either  receive  XML messages  or  query HMIS  system  databases  to  keep  the Homeless REACH application bed counts up‐to‐date and searchable.   During our visit to Red Bank, NJ, we learned that many shelters update the New Jersey HMIS when they have the opportunity to do so versus being a real‐time count.  In support of potential ways to improve the timing and dissemination of data to caregivers of bed counts we have implemented two innovative features:   

  

3

“Shelter Bed” Application ‐ This allows shelters to register through our website and gives them the ability to manage bed counts in real time through the web or through a device application.  This  simple  interface  allows  shelters  to  change bed  count numbers  as people  come  and  go from the facility.   This may improve the way data is collected, and may be a future expansion point to support reporting of this data to the CoC HMIS system through an automated process. 

Push  Notifications  ‐  This  gives  the  user  the  ability  to  “bookmark”  a  shelter  and  receive notifications when  the  shelter has bed availability. We  created  this  feature  in  response  to a current need to search for beds actively and to see  if there  is availability at a specific facility.  By providing a push notification feature, we allow a caregiver or person helping the homeless to  automatically  receive  availability  changes  versus  them  having  to  manually  monitor availability. 

 

SustainabilityThe goal of Project REACH is a free app that is widely available so that as many people as possible experiencing homelessness and working with the programs that serve the homeless can get help.  Please describe how you plan to sustain your app long‐term as a free service after the contest ends.  Judges will consider and evaluate whether your proposed strategy is practical and achievable. 

 Please limit your response to 1,000 words. Qbase is committed to releasing the iOS and Android versions of the Homeless REACH application at no charge to the public Apple App Store and Google Android Marketplace at the end of the second Beta test  phase  and  prior  to  final  judging  of  the  Project  REACH  contest.  The  website, https://homelessreach.info, has been live since our original submission and is accessible to anyone via a web browser.   We recognize funding will be required in order to: sustain the applications; add additional data sources HMIS systems; provide maintenance and improvement of the apps; and to support the website. As part of  this understanding, Qbase has  limited  the  infrastructure  costs by hosting  the  servers  required  to push data to the apps and website within our data center located in Dayton, Ohio. This offers several advantages because  it allows us  to  leverage Qbase’s current capabilities  for  internet access, cooling, power, and processing time. It eliminates the need to pay for private or public cloud hosting, which can grow and become costly as the number of users and data sources  increases during a national rollout. We  are  confident  Qbase’s  current  server  and  equipment,  which  is  running  the  Homeless  REACH platform, can support between 10,000 and 25,000 concurrent users at any given time.   In addition, Qbase looked at the type advertisements displayed on similar sites and apps, as well as, current sites that host shelter and food bank information to understand their model. We also investigated in‐app advertising, which we believe would be the most frequently used form of the Homeless REACH platform, and evaluated whether ads could be placed in the app. Our analysis demonstrated that both the website and in‐app advertising distracts from the user experience and defeated the purpose of obtaining accurate data quickly. Moreover, since advertisement links typically only reimburse a few cents per click, they would not generate enough revenue to sustain the application in the manner the VA is seeking.  As a  result, Qbase has  researched  sponsorship based advertising  from  system  integrators and other commercial companies. Using this model, entities could make donations to Project REACH.  In return, they would receive prominent logo placement and links to their website describing their support of the VA and HUD initiatives to end homelessness within the application. This model is similar to other self‐funded  initiatives,  such  as  the Maui  Economic  Development  Board, where  companies  sponsor  the board by paying yearly dues at different tier levels. Each tier level allows the company to be promoted 

  

4

in the community and  the  funds are used to develop and promote growth  in the area. Furthermore, this approach would not disrupt or distract the user experience.  For REACH,  tier  levels will be based on  the  company’s  size and  they would  receive  the promotional rights  to  affiliate  themselves  with  this  important  initiative.  Donations  are  then  held  in  an  escrow account  so  funds  to  further develop  and maintain  the  application  are  readily  available.  In  addition, excess  funds  in  the  account  would  be  donated  to  homeless  charities  or  rolled  over  to  provide continued sustainment of the application platform at the end of each year.   We have already  reached out  to  several  companies,  including SAIC, Northrop Grumman, Booz Allen Hamilton,  SRA  International, PSI, 7Delta,  and  the BITS Group,  and  all of  them have  expressed  their interest to learn more about this opportunity to support the VA. We predict this model could generate at  least 60% of the funds required for continued development of the application and sustain the app over the next couple of years.    Our research and conversations with CoCs in Arlington, VA and Los Angeles, CA have also revealed that long term community adoption and access to HMIS data to support Shelter Bed Availability will require government support from the VA or HUD.  Specifically, in conversations with Arlington about accessing their HMIS data,  it was noted that HMIS systems contain Personal Identifiable Information (PII) about the homeless. This would make  it very difficult, and even unlikely,  for an  independent  third party  to communicate directly with their system. However, Qbase believes having an agency like the VA or HUD sponsor the app as part of an initiative to assist the homeless would supply the required visibility and influence for the CoCs and HMIS repositories to provide the data required to support and sustain the app.  Qbase  believes  a  combination  of  government  support  and  private  company  donations  is  the most viable  solution  for  supporting  the ongoing development, upkeep,  and expansion of  this  app  for  full national deployment.   As  part  of  the  app  sponsorship,  Qbase  would make  the  application  webservices  and  source  code available to the Open Source community to allow the platform to become the Government Resource for other applications. In this manner the VA and HUD would become the central authority and registry for these types of services because it provides the most accurate resource for other apps and services that may be developed beyond the REACH community. For example, the data collected and stored  in the REACH platform  for Transportation,  Legal, VA Facilities, and Health Facilities,  can be adopted  in other planned applications issued by the Government as part of broader mobile application strategies.   Overall, Qbase is committed to sustaining the application and maintaining the application as a free and open  resource  for  the  public  to  use  through  this  approach.    Our  conversations  with  caregivers, including the visits we made to the Soul Kitchen, Lunch Break, and Monmouth Resource Center, as well as our discussions with the CoC  in Arlington, VA  in Los Angeles, CA, have further confirmed the need and potential value this kind of app would provide.  

 

How will your app ensure functional performance as you scale? Throughout the Project REACH contest, Qbase has architected its platform using enterprise design best practices and principles. Moreover, we understand that performance in this design is measured by the User and their perceptions and experiences with our applications. Therefore, Qbase has been working to maintain and in some cases improve performance of our platform to account for the expected influx of new users upon release and the continually growing amounts of data we have been collecting on places and services. The following techniques are employed in our platform to ensure scalability and performance:

Asynchronous Processes

REST Services

Caching

Hardware and Software Tuning

Load Balancing and Clustering

Asynchronous Processes. On the data side, we built automated Extract Transform and Load (ETL) processes that mine the registry, databases, and webservices providing the Place and Service data presented in our mobile and web applications. The ETL process runs independently on our servers and populates our database asynchronously with new data. The ETL process performs the data clean up and geocoding function allowing the mobile applications to search based on GPS location or by full or partial address. These processes run autonomously during low-peak times, e.g., early morning hours. Loading failures are pushed to a database table and can be manually acted upon by an administrator for retry. These failures are typically address parsing errors or invalid addresses causing a geocode failure. Both of these failures can be corrected and remembered so as not to happen during subsequent ETL processes. Currently we have approximately 110,000 places and services across the country with fewer than 5% failures. REST Services. Our REST services are designed to handle performance of mobile devices by offering the ability to “page” or retrieve subsets of results. This feature allows apps to pull small amounts of relevant data at a time versus pulling everything all at once, which can cause performance problems as more data is added. Within the iOS and Android application, we have implemented several performance strategies that enable the app to handle the large amount of data available while maintaining usability for the end user. As an example, both our iOS and Android application use the “paging feature” of the REST service to pull small sets of data at a time from the server based on the search performed by the user. When the user “scrolls” to the end of the fetched set of data, the apps automatically fetch the next set in the background. This performance technique allows a user to search, retrieve, and pull data quickly in a responsive manner. This also reduces the amount of data, pulled by the App at any given time, limiting the impact on user data plans by not receiving the entire database for each search performed.

As another example of functional optimization within the apps, we use a technique called “lazy loading” for all images displayed in the search results. This technique provides the ability to quickly fetch the text portion of the search results separate from the images. Images are pulled when a specific result is displayed on the screen through a background thread process. This provides Homeless REACH two functional performance advantages: Fast Loading of Textual Data and Asynchronous Loading of Larger Image and Binary Data. Text is smaller in size than image data, so by sending the text portions of the results separate from the images, the information can be retrieved much faster than pushing both at once. By only loading images when the result is displayed by the user reduces the amount of data consumed by the end user device to which reduces total memory usage and speeds up the responsiveness of the app thereby enhancing the user experience. Another feature that we have implemented that helps users with the functional performance is the ability to filter results to only display places and services that meet certain criteria. This feature provides three key benefits to the end user.

First, by allowing users to search for places and services using criteria such as a search radius, name, open bed availability, or specific shelter type, this limits the result set returned to a narrow and specific set of data versus returning all data all the time.

Second, by using the filters, the amount of data pushed to the device is smaller resulting in very fast response times which enhances the user experience.

Third, our data model which supports this function allows for future growth and expansion as we can add more filters and metadata through configuration allowing for more detailed or enhanced searching to occur in the future.

This ultimately means we can provide more ways for a user to find specific services within a geographic region by providing them with more options to search and retrieve data. Caching. The Homeless REACH platform uses “caching”, the storing of information retrieved from external services locally in our database, to speed up the servicing of REST requests. For example, our platform offers location based searches in both its mobile and web applications. Location based services require a geocoding engine and a reverse geocoding engine. The geocoding engine takes a partial or full address and provides a latitude and longitude. The reverse geocoding engine takes a latitude and longitude and provides a partial or full address. Both processes require a high amount of system resources. In some cases, both processes are limited to the number of requests allowed per day; an example is Google Maps API is limited to 25k requests a day. Our platform uses a cache to store a latitude and longitude for a requested address and as such the same cache also makes that address available to the reverse geocoding engine. Therefore, our use of caching curtails system resource usage and mitigates hitting any request limitation ceilings. Hardware and Software Tuning. We utilize a large, multi-processor server to house the services, database, and application server for Homeless REACH. This server has been tuned to handle up to 20-30,000 concurrent users, pulling information from the REST services from their mobile devices or via the internet through the website.

The Qbase Homeless REACH platform is currently running on mostly open source software including Apache HTTP server, Glassfish Application Server, and PostgreSQL Relational Database Server with the PostGIS extension. These services are popular, widely used, and performance tuning documentation is plentiful. We have used the documentation to performance tune the applications accordingly. Load Balancing and Clustering. Our platform can be load balanced and clustered. As mentioned above, we are using Apache, Glassfish and PostgreSQL, each of which is clusterable. We are currently using load balancing to separate the ETL processes and the User’s use of the REST services. They are currently in two different Glassfish domains, the ETL processes use one domain while the User applications use the other, both pointing at the same database. Will you be tracking information about app usage or about the app’s users? Qbase understands the concerns of privacy and use of individuals’ information that could be gathered from the use of a mobile or web applications. Therefore our applications do not track or keep any information about a user within the Homeless REACH platform. From an app usage standpoint, we are using Google Analytics to track the REST services used and the performance of the application and responsiveness of the system. This information is anonymous in that it cannot be tracked back to any user. What it does provide is the average load statistics on our servers and usage patterns, including response times of both the website and REST services. This information provides us with useful guidance on where issues are and areas where we can improve the user experience. When the apps are released to the public through the Apple Store and Google Play, we will be able to track how many times the iOS and Android apps have been downloaded. Will you be tracking the information, location, and/or identity of the user? No, our application platform is “stateless” in the sense we do not store, log, or cache any information about a specific user of the app or the queries they are making. Our Homeless REACH app also does not require a login to use, so we have no information on a user who has downloaded and is using the app. When the user makes a query for resources near a location the app will send the REST service a latitude/longitude or full or partial address so that places and services can be found near that location. However, the REST service does not track, store, or receive any information about the user calling the REST service. For device notifications, we are using the Apple Push Notification Service and the Google Cloud Messaging services. The use of these messaging services abides by the terms of services and strictly adheres to the suggested coding practices of both Apple and Google with respect to privacy concerns and the ability to provide device notifications. To use these services, we receive a unique token (not the device UUID which is identifiable) from Apple or Google that is based on our signing certificate for the app.

The process for registering a device to use this service can be found here for Apple (http://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Introduction/Introduction.html#//apple_ref/doc/uid/TP40008194-CH1-SW1) and here for Google (http://developer.android.com/guide/google/gcm/index.html). In both cases, a user who allows the app to receive notifications gets a unique key tied to the app and their device from Apple or Google. This key is stored on the REACH servers, which allows the REACH platform to send push notifications to Apple or Google, who ultimately sends the notification to the device. The key on its own is not traceable to a specific device and none of the REACH platform REST calls uses the notification key beyond registration and management of subscribed alerts. As part of our research into improving care for the homeless, we investigated whether or not we should develop an app for capturing HMIS data that is gathered on a homeless person to be able to “pre-register” them within a HMIS system as a way to simplify and improve “Outreach” . Part of the required data set for the HMIS system to be able to track homeless captures the SSN, Birthdate, Sex, and other identifiable information on the person. In talking to CoCs in Virginia and Los Angeles, we also realized that this information is captured already when they are registered at a center as part of the reporting requirements for centers receiving funds through HUD or VA programs. While we see that there is an opportunity to provide a central registration capability to help track and care for those in need, we also realized that this level of responsibility resides at the CoCs themselves. We also evaluated the risks of creating an app for broad public consumption that allows individuals to capture, store, and send personal identifiable information and realized that this type of app had the potential to be misused and storing and sharing this information from the app to the CoC would require special data use agreements and security requirements. Therefore, we decided against developing an app that could allow someone to capture a persons identifiable traits, and approached OutReach in a different manner. Specifically, using the push notifications noted above, we allow a user to monitor shelters (where this information will ultimately be taken by an authoritative entity) for when beds become available, this allows a caregiver to immediately call and start the process as soon as they are notified. To also facilitate the intake process, we added the ability for shelters to describe their intake process by modifying their profile on the website. This information is then pushed to the devices as part of the search results, as well as being visible on the website. This allows a user to find shelters that have intake and screening processes as well as shelters that do not. With regard to the “Shelter Bed” capability, does a service provider have to log in to be able to update the beds in real-time? If yes, what is the account setup process? Yes, we use a login and password to tie a user to places and in particular shelters to manage bed counts in real-time. The user can login via the website on a standard computer or through an Android device, or use the iOS app for managing beds natively. Below are instructions for establishing an account and associating the account with a shelter. We are in the process of evaluating a more rigorous signup and verification process than what is described below. For example, Homeless REACH links its places with Google Places, therefore, an adjudication process that includes Google Places to validate and verify that the user is truly the business

owner orthat the u Furthermor third pdecremen Below de 1) To us

To us1) R

ht2) O

nw

3) A

Note: Ththe Bed Acounts in

1) T

lo

r person respuser is author

more, the proparty applicanting bed co

escribes the

se the VASh

se the Bed MRegister to us

ttps://homelOnce on the s

ame of the pwill appear. C

An email will

his account aApplication n Real-Time.

To manage beogin screen (

ponsible to mrized to man

cess describation can encunts for a pa

process for r

helterBed app

Management se the Bed Messreach.infosite, search fplace. This aClick this bu

l be sent wit

allows you toManagemen.

M

eds from the(Figure 3)

manage the sinage bed cou

bed below macapsulate thearticular shel

registering b

plication for

ApplicationManagement fo for the place ction will di

utton to begin

Figure 1: Hom

th further ins

o login into tnt App, VAS

Managing B

e web, click

Figure 

ite is one opunt at a speci

akes use of oe workflow rlter.

beds

r managing B

n follow the sApplication

that you’d lisplay the plan managing t

meless REACH W

structions on

the website tShelterBed, f

Beds from th

on “My Plac

2: My Places Ico

ption. Adjudiified shelter.

our REST seregistering a

Beds follow

steps below.n at our webs

like to managace details athe place.

Website

n how to acti

to manage bfrom your iP

he Web:

ces”. (Figur

on

ication is req.

ervices. In tha user and inc

the instructi

. site (Figure

ge. Click theand a “Manag

ivate your ac

bed numbers Phone or iPad

re 2) which w

quired to ins

heory, any decrementing o

ions below.

1)

e details iconge Place” bu

 

ccount.

as well as ud to manage

with take you

sure

evice or

n or utton

use e bed

u to

 

2) E3) O

4) Tm

Clicking immediat

Enter in your Once logged

This should bmanage on th

on ‘Check-Itely availabl

Figu

Username ain – Select G

bring you to he web. (Figu

In’ will decrle to the VAH

ure 3: Homeless 

and passwordGo under Be

Figure 4: Bed

a screen witure 5)

Figure 5: Be

rease the remHomeless A

REACH Website

d. ed Managem

d Management 

th the associa

d Management 

maining bed cApp for real t

e Log in Screen

ment on the lo

Option

ated shelter,

Screen

count. This itime bed man

ower left pan

 

and bed Ty

information nagement.

 

ne. (Figure 4

ype you can

 

once set is

4)

1) TVp

2) O7)

To manage beVAShelterBe

assword you

Once Logged7)

eds from theed applicatiou registered o

Figure 6

d in – Click o

F

VAShelter

e VAShelterBn on your iPon the site w

: Mobile VAShe

on ‘Bed Stat

Figure 7: Mobile

rBed Applic

Bed applicatPhone or iPadwith. (Figure

lterBed Applica

tus’ to bring

 e Bed Managem

cation:

tion on the md and enter ie 6)

tion Sign‐in Scre

up the Bed M

ment Screen

mobile devicin the userna

een

Managemen

ce, launch thame and

nt Pane. (Fig

he

gure

Clicking on (+) for ‘Check In’ removes a bed from the remaining count, clicking on (–) for ‘Check out’ adds a bed back to the available bed count for this bed type at this shelter. Like the web application this information is immediately available to the VAHomeless Application.  Could you provide code snippets from your RESTful Web Services/API?  

Please see attached API guide for full details of the deployed RESTful calls, Sample for Querying Beds near Red Bank Lat=40.360172 Lon= - 74.083206 within a radius of 5 miles.  REST Call ‐‐ https://challenge.qbaseit.com/reach/rest/places/search?types=3&latitude=40.360172&longitude=-74.083206&distance=5&limit=25

  JSON Returned  {"data":[{"items":[{"distance":1.3809775193095837,"place":{"classType":"Place","active":true,"address":{"address1":"212 South Pearl St","address2":null,"city":"Red Bank","geoCoderAddress":"212 South Pearl St, Red Bank, NJ 07701","geoCoderClass":"MetaCartaClient","geoCoderRating":"1.000000","geoCoderRequired":false,"latitude":40.3427,"longitude":-74.0703,"md5AddrDiscreteHash":"c44614664beb3e40da37cc3d40deae30","md5AddrProbHash":"ff720c921483855da6a0da4b1a0aadbd","singleLine":"212 South Pearl St Red Bank, NJ 07701","stateAbbr":"NJ","zipCode":"07701"},"dateCreated":1348068290414,"dateUpdated":1348068290414,"description":null,"md5NameDiscreteHash":"d5d4df07cfa6acdd028db6279e27dfd9","md5NameProbHash":"080dec0f618707a77d1520d600989f2e","name1":"HABcore","name2":"HABcore -Coffey Residence Respite - Monmouth","phoneInformation":{"fax":null,"mobile":null,"other":null,"work":null},"placeAlert":null,"placeId":72,"pointsOfContact":[{"active":false,"dateCreated":1348068290416,"dateUpdated":1348068290416,"firstName":"Steve","lastName":"Heisman","phoneInformation":{"fax":null,"mobile":null,"other":null,"work":"7322248200"},"placeContactId":72,"socialMedia":{"email":null,"facebook":null,"twitter":null,"webpage":null},"title":null,"verified":false}],"serviceOfferings":[{"classType":"ShelterOffering","attributes":[{"attributeTypeId":5,"description":"Emergency Shelter","serviceType":{"description":"Housing","serviceTypeId":3,"name":"3","value":"Housing"},"name":"5","value":"Emergency ….. cut ….

        

1 of 21

Homeless Reach

REST Services Bed Count ............................................................................................................................................................. 2 Hotlines ................................................................................................................................................................. 3 Import Place .......................................................................................................................................................... 4 Import Bed Count .................................................................................................................................................. 6 Import Place Exists ............................................................................................................................................... 7 Import Deactivate Places ...................................................................................................................................... 8 Lists User Selection Types ................................................................................................................................... 9 Lists User Selections .......................................................................................................................................... 10 Place Alert .......................................................................................................................................................... 11 Device Alerts ....................................................................................................................................................... 12 Registered Device .............................................................................................................................................. 13 Place Search ...................................................................................................................................................... 14 Job Search .......................................................................................................................................................... 15 Place Details ....................................................................................................................................................... 16 Place Default Image ........................................................................................................................................... 17 Place Image ........................................................................................................................................................ 18 User Details ........................................................................................................................................................ 19 User Registration ................................................................................................................................................ 20 Appendix Shelter Bed Type ................................................................................................................................ 21 

2 of 21

Bed Count Increments bed count on a Place per bed type.

Path /bedcount/{placeid}/{bedtype}

Security Requires authentication, user role of PLACE-ADMIN and a link to {placeid}

HTTP Method POST

Parameters Name Where Type Description placeid Path Long primary key of place bedtype Path String code for bed type; see Appendix Shelter Bed Types increment Request Long +/- bed increment, a negative increment will decrement the beds in

use.

Example https://example.com/reach/rest/bedcount/1/HC?increment=1

3 of 21

Hotlines Retrieves a list of hotlines.

Path /hotlines

Security None

HTTP Method GET

Parameters None

Example https://example.com/reach/rest/hotlines

4 of 21

Import Place Receives JSON of a place and puts it on queue for importing.

Path /import/place

Security Requires authentication and user role of REACH-INTERNAL-SYSTEM-ADMIN Default user/password: admin@4qbase.com/password

HTTP Method POST

Parameters None - Body of HTTP request is the JSON for import. { address: address, sourceInformation: true, place: { classType: "Place", name1: Agency, name2: Program, description: null, serviceOfferings: [{ classType: "ShelterOffering", attributes: [{ description: HousingType }], serviceType: { serviceTypeId: 3 }, shelterBedTrackers: [{ bedsInUse: Occupied, bedsRemaining: Open, totalBedCount: BedUnits, shelterBedType: { code: shelterbedtypecode } }] }], phoneInformation: { work: phonework, fax: null, mobile: null, other: null }, socialMedia: { twitter: null, facebook: null, webpage: null }, pointsOfContact: [{ firstName: pocfirstname, lastName: poclastname, title: null, phoneInformation: { work: pocphonework }, socialMedia: { twitter: null, facebook: null, webpage: null

5 of 21

} }] }, importPlaceInformation: { filename: importfile, rownum: rownum, runTag: importruntag, transform: importtransform, uniqueIdentifier: importquickref } }

Example https://example.com/reach/rest/import/place

6 of 21

Import Bed Count Set bed count on a Place per bed type.

Path /bedcount/{placeid}/{bedtype}

Security Requires authentication and user role of REACH-INTERNAL-SYSTEM-ADMIN Default user/password: admin@4qbase.com/password

HTTP Method PUT

Parameters Name Where Type Description placeid Path Long primary key of place bedtype Path String code for bed type; see Appendix Shelter Bed Types Request body is JSON: {

bedsInUse: Long - Set beds in use or beds occupied (required) bedsRemaining: Long - Set beds remaining or beds open (required) totalBedCount: Long - Set total bed count (required)

}

Example https://example.com/reach/rest/bedcount/1/HC

7 of 21

Import Place Exists Receives JSON of a place and returns a place if it exists.

Path /import/exists

Security Requires authentication and user role of REACH-INTERNAL-SYSTEM-ADMIN Default user/password: admin@4qbase.com/password

HTTP Method POST

Parameters None - Body of HTTP request is the JSON for import.

Example https://example.com/reach/rest/import/place/exists

8 of 21

Import Deactivate Places Used during import to set the active flag of places to false. TODO - Not yet implemented.

Path /import/deactivate/{servicetype}/{transform}

Security Requires authentication and user role of REACH-INTERNAL-SYSTEM-ADMIN Default user/password: admin@4qbase.com/password

HTTP Method PUT

Parameters Name Where Type Description servicetype Path Long primary key of service offering type transform Path String name of etl transform

Example https://example.com/reach/rest/import/deactivate/5/TfmMentalFacilities

9 of 21

Lists User Selection Types Retrieve a list of user selectable types.

Path /lists

Security None

HTTP Method GET

Parameters None

Example https://example.com/reach/rest/lists

10 of 21

Lists User Selections Retrieve a list of name/value pairs for a type.

Path /lists/{type}

Security None

HTTP Method GET

Parameters Name Where Type Description type Path Int type of resource;

ServiceType(1), ShelterBedType(2), AttributeType(3);

Example https://example.com/reach/rest/lists/1

11 of 21

Place Alert Create, delete, and retrieve alert.

Path /alerts/{devicetype}/{deviceuuid}/{placeid}

Security None

HTTP Method GET - retrieve alert POST – create and update alert DELETE - delete alert

Parameters Name Where Type Description devicetype Path Int device type code; (required)

-1 : ‘Test Device’, 1 : ‘Apple iOS’, 2 : ‘Google Android’

deviceuuid Path String uuid of device (required) placeid Path String primary key of place (required) enddate* Request String date in ISO format (yyyy-MM-dd) times* Request Int number of times to send alert *only relevant for POST (creating or updating alert)

Example https://example.com/reach/rest/alerts/1/123456789/42?times=4

12 of 21

Device Alerts Retrieves all alerts for a device.

Path /alerts/{devicetype}/{deviceuuid}

Security None

HTTP Method GET

Parameters Name Where Type Description devicetype Path Int device type code; (required)

-1 : ‘Test Device’, 1 : ‘Apple iOS’, 2 : ‘Google Android’

deviceuuid Path String uuid of device (required, this is the UUID returned from Apple or Google for Messaging Notifications)

Example https://example.com/reach/rest/alerts/1/12343579

13 of 21

Registered Device Create, delete, and retrieve registered devices.

Path /devices/{devicetype}/{deviceuuid}

Security None

HTTP Method GET - retrieve registered device details POST - create registered device DELETE - delete registered device

Parameters Name Where Type Description devicetype Path Int device type code; (required)

-1 : ‘Test Device’, 1 : ‘Apple iOS’, 2 : ‘Google Android’

deviceuuid Path String device uuid (required, this is the UUID returned from Apple or Google for Messaging Notifications)

Example https://example.com/reach/rest/devices/1/123456789

14 of 21

Place Search Searches for places, sending ‘deviceuuid’ and ‘devicetype’ will return any alerts.

Path /places/search

Security None

HTTP Method GET

Parameters Name Where Type Description Address Request String string of address (required*) Latitude Request Double latitude of center (required*) Longitude Request Double longitude of center (required*) Name Request String name of place to match in search Latlngvalid Request Boolean true or false to defer to address Distance Request Double radius of search (required) Types Request String Filter, CSV of place type codes Offset Request Int page item offset Limit Request Int items per page limit Onlyopen Request Boolean Filter, return only shelters with open beds Bedtypes Request String Filter, CSV of bed types to return Attributes Request String Filter, CSV of attribute codes to return Devicetype Request Int device type code;

-1 : ‘Test Device’, 1 : ‘Apple iOS’, 2 : ‘Google Android’

Deviceuuid Request String Uuid of device (optional, this is the UUID returned from Apple or Google for Messaging Notifications)

*Either use address or latitude/longitude combination. Address will be geocoded, providing search center latitude and longitude.

Example https://example.com/reach/rest/places/search?address=100+Granny+Apple&distance=5

15 of 21

Job Search Searches for jobs.

Path /jobs/{type}

Security None

HTTP Method GET

Parameters Name Where Type Description Type Path Int Job search type: All(0), CareerBuilder(1),

NRD(2), Indeed(3), SimplyHired(4) Address Request String string of address (required*) Latitude Request Double latitude of center (required*) Longitude Request Double longitude of center (required*) Distance Request Double radius of search (required) Keywords Request String CSV list of keywords to search with Orkeywords Request Boolean Whether to OR keywords, default is AND Moc Request String Moc code Offset Request Int page item offset Limit Request Int items per page limit *Either use address or latitude/longitude combination. Address will be geocoded, providing search center latitude and longitude. A provide latitude/longitude will be reverse geocoded.

Example https://example.com/reach/rest/jobs/1?address=100+Granny+Apple&distance=5

16 of 21

Place Details Retrieves place details, sending ‘deviceuuid’ and ‘devicetype’ will return any alerts.

Path /places/{placeid}

Security None

HTTP Method GET

Parameters Name Where Type Description placeid Path Long primary key of place (required) devicetype Request Int device type code;

-1 : ‘Test Device’, 1 : ‘Apple iOS’, 2 : ‘Google Android’

deviceuuid Request String Uuid of device (optional, for testing)

Example https://example.com/reach/rest/1

17 of 21

Place Default Image Retrieves default place image. The method returns a pre-configured “missing image” if no image is found. The method is shorthand for /images/place/{placeid}/1 and returns the SnapShot image type.

Path /images/place/{placeid}

Security None

HTTP Method GET

Parameters Name Where Type Description placeid Path Long primary key of place

Example https://example.com/reach/rest/images/place/1

18 of 21

Place Image Retrieves place image. The method returns a pre-configured “missing image” if no image can be found. In the case of StaticMap and StreetView, the method will retrieve an image from Google and store it for subsequent retrievals.

Path /images/place/{placeid}/{imagetype}

Security None

HTTP Method GET

Parameters Name Where Type Description placeid Path Long primary key of place imagetype Path Int image type code

StaticMap(2), SnapShot(1), StreetView(3);

Example https://example.com/reach/rest/images/place/1/1

19 of 21

User Details Retrieves users’ details.

Path /users/me

Security Requires authentication and user role of PLACE-ADMIN

HTTP Method GET

Parameters None

Example https://example.com/reach/rest/users/me

20 of 21

User Registration Registers a user. TODO needs more thought. Should put everything on URL path.

Path /users

Security None - TODO needs more thought

HTTP Method POST

Parameters Name Where Type Description email Request String user email address md5password Request String MD5 hash of password places Request String CSV of place ids to link with account

Example https://example.com/reach/rest/users?email=fred@bedrock.com&md5password=sdfsfklh&places=1,3,42

21 of 21

Appendix Shelter Bed Type ('HC','Households with Children'); ('SF+HC','Single Females and Households with Children'); ('SF','Single Females 18years and older'); ('SM+HC','Single Males and Households with Children'); ('SM','Single Males 18years and older'); ('SMF+HC','Single Males and Females and Household with Children'); ('SMF','Single Males and Females 18years and older'); ('YF','Young Females under 18'); ('YM','Young Males under 18'); ('YMF','Unaccompanied Young Males and Females under 18'); ('U','Unspecified population served');