Sections

» Introduction
» Public
» Hosts
» Students
» Placements
» Agents
» Admin

Developers

» Apply

Hosts

Authentication required

Successful authentication provides the developer with access to the Host data for their supervising organisation. The Homestay Network API provides access to Host data in the RESTful approach (GET, POST, PUT, DELETE). All requests must provide the token parameter.

List hosts

Returns title, address and other basic information for all Hosts supervised by the organisation.

Name Description
id The unique identifier in the AHN database
name The name of the contact
address The street address for the host
city The name of the city
host-status The status of the host's application

GET: http://api.homestaynetwork.org/hosts/?token=xxxxx

Response

<hosts>
	<host>
		...
	</host>
	...
</hosts>

Get host

Returns the full profile data for an individual host under the supervision of the developer's organisation.

GET: http://api.homestaynetwork.org/hosts/(host-id)?token=xxxxx

host-id relates to the Id column of the Host model in AHN.

Response

<host>
	...
</host>

Create host

Create a new record for a host in the AHN database. The request must be in the POST format and the following data parameters must be sent:

In aphabetical order (required in red):

Model Parameter Data Type Description Options
user username string(50) The username for accessing the system
user email string(150) The primary email address for the host
user family_name string(80) The family name of the main contact for the host
user given_names string(80) The given names of the main contact for the host
host additional-costs string(1000) Information on the additional costs that may be incurred by students
host address string(250) The street address and suburb (excluding city, state)
host bank-account string(12) Bank account number
host bank-account-name string(50) Name of the host's bank account
host bank-bsb string(8) BSB of the host's bank
host bank-name string(50) Name of the host's bank
host brief-description string(250) Brief (25 words or less) description of a host.
host campus-id integer Id of the host's preferred campus (Education provider) Campuses
host can-accommodate-couple boolean Whether the host can accommodate a couple True/False
host city-id integer Id representing the host's city Cities
host existing-host boolean Whether the host is an existing host with your organisation True/False
host fax string(20) The host's facsimile (fax) number
host has-pets boolean Whether the host has pets or not True/False
host host-availability-type integer The type of availability 1 = Always available
2 = Limited availability
host host-rating-id integer The host's rating 1 = Gold
2 = Silver
3 = Bronze
host host-service-id integer The level of service offered Services
host include-in-family-activities boolean Whether the host will involve students in family activities True/False
host internet string(2) The type of internet the host has connected NA = No connection
DU = Dial up
BB = Broadband
WI = Wireless Broadband
host internet-available-to-students boolean Whether the host's internet connection is available to the student True/False
host language-id integer The first language of the host Languages
host number-of-beds integer The number of beds available to students
host number-of-rooms integer The number of rooms available to students
host pets string(250) Details of the types (breed, size, personality etc) of the host's pets
host phone-home string(30) The host's home phone number
host phone-mobile string(30) The host's mobile phone number
host phone-work string(30) The host's work phone number
host placement-length string(1) The preferred placement length s = 6 weeks or less
l = Longer than 6 weeks
n = No preference
host post-code string(8) The host's postal/zip code
host postal-address string(250) The full postal address for the host (if different to their home address)
host preferred-age string(3) The preferred age of students to host 18- = Under 18
18+ = Over 18
Any = No preference
host preferred-gender string(1) The preferred gender of students to host m = Male
f = Female
e = Either
host preferred-nationality-religion string(100) Will they host any nationality or cultural background?
host profile-content text The full HTML content for a host's profile
host provide-private-bathroom boolean Whether the host can provide a private bathroom for a student True/False
host provide-transport boolean Whether the host can provide daily transport to the student's campus True/False
host second-language-id integer The host's second language Languages
host smoke-detector boolean Whether there are smoke detectors fitted in the house/apartment True/False
host smoking boolean Whether the host smokes True/False
host special-diet-details string(250) Details of any special dietary requirements the host can cater for
host students-can-smoke integer Whether the student is allowed to smoke 1 = Yes
-1 = No
0 = Outside only
host take-on-excursions boolean Whether the host is willing to take the student on excursions True/False
host will-host-under-18s boolean Whether the host will host students under the age of 18 True/False
host will-host-vegetarian boolean Whether the host will host vegetarian students True/False
host zone string(20) The regional zone/area the host is located within (specific to the organisation)

POST: http://api.homestaynetwork.org/hosts/?token=xxxxx

The host data may be posted with the request as XML in the following format:

<request>
	<user>
		<given_names>Joe</given_names>
		<family_name>Bloggs</family_name>
		<email>joe@mail.com</email>
		...
	</user>
	<host>
		<address>25 Foobar St</address>
		<city_id>12</city_id>
		...
	</host>
</request>

Response

<response>
	<status>201</status>
	<message>xxx</message>
</response>

Note: The 'message' refers to the Id of the new host record.