HSDA Taxonomy

The HSDA taxonomy protocol is defined by openapi-hsda-taxonomy.yaml. The details below show the available methods and responses.

This is a separate HSDA service for working with taxonomy across all the core human services resources, support any categorization or taxonomy, and allowing for filtering of services by taxonomy.

You can also explore this using our OpenAPI viewer.

Warning

This is an experimental feature. Feedback is welcome to shape its further development.

GET /taxonomy/

Get Taxonomy

Get Taxonomy

Status Codes

200 Response Body:

Description

Type

Required
id

Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.

string

True
name

The name of this taxonomy term or category.

string

True
parent_id

If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.

string

False
parent_name

If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.

string

False
vocabulary

If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.

string

False
POST /taxonomy/

Add taxonomy

Addtaxonomy

Status Codes

200 Response Body:

Description

Type

Required
id

Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.

string

True
name

The name of this taxonomy term or category.

string

True
parent_id

If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.

string

False
parent_name

If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.

string

False
vocabulary

If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.

string

False
GET /taxonomys/{taxonomy_id}/

Get Taxonomy

Get Taxonomy

Parameters

  • taxonomy_id (string) – The taxonomy id.

Status Codes

200 Response Body:

Description

Type

Required
id

Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.

string

True
name

The name of this taxonomy term or category.

string

True
parent_id

If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.

string

False
parent_name

If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.

string

False
vocabulary

If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.

string

False
PUT /taxonomys/{taxonomy_id}/

Update Taxonomy

Update Taxonomy

Parameters

  • taxonomy_id (string) – The unique taxonomy id.

Status Codes

200 Response Body:

Description

Type

Required
id

Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.

string

True
name

The name of this taxonomy term or category.

string

True
parent_id

If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.

string

False
parent_name

If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.

string

False
vocabulary

If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.

string

False
DELETE /taxonomys/{taxonomy_id}/

Delete Taxonomy

Delete Taxonomy

Parameters

  • taxonomy_id (string) – The taxonomy id.

Status Codes

200 Response Body:

Description

Type

Required
id

Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.

string

True
name

The name of this taxonomy term or category.

string

True
parent_id

If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.

string

False
parent_name

If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.

string

False
vocabulary

If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.

string

False
GET /services/{taxonomy_name}/

Get Services

Get Services

Parameters

  • taxonomy_name (string) – The taxonomy name.

Query Parameters

  • query (string) – A query to filter list by (up to provider to determine what to search)

  • queries (string) – A comma separate list of queries with specific fields.

  • page (number) – The particular page of results.

  • per_page (number) – Number of records return per page, up to 100.

  • sort_by (string) – Which field to sort by.

  • order (string) – Which order to sort by (asc,desc).

Status Codes

200 Response Body:

Description

Type

Required
id

Each service must have a unique identifier.

string

False
organization_id

The identifier of the organization that provides this service.

string

False
program_id

The identifier of the program this service is delivered under.

string

False
location_id

The identifier of the location where this service is delivered.

string

False
name

The official or public name of the service.

string

False
alternate_name

Alternative or commonly used name for a service.

string

False
description

A description of the service.

string

False
url

URL of the service.

string

False
email

Email address for the service.

string

False
status

The current status of the service.

string

False
interpretation_services

A description of any interpretation services available for accessing this service.

string

False
application_process

The steps needed to access the service.

string

False
wait_time

Time a client may expect to wait before receiving a service.

string

False
fees

Details of any charges for service users to access this service.

string

False
accreditations

Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.

string

False
licenses

An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.

string

False
GET /services/complete/{taxonomy_name}/

Get Services (Complete)

Get Services (Complete)

Parameters

  • taxonomy_name (string) – The taxonomy name.

Query Parameters

  • query (string) – A query to filter list by (up to provider to determine what to search)

  • queries (string) – A comma separate list of queries with specific fields.

  • page (number) – The particular page of results.

  • per_page (number) – Number of records to return per page, up to 100.

  • sort_by (string) – Which field to sort by.

  • order (string) – Which order to sort by (asc,desc).

Status Codes

200 Response Body:

Description

Type

Required
id

Each service must have a unique identifier.

string

True
organization_id

The identifier of the organization that provides this service.

string

True
program_id

The identifier of the program this service is delivered under.

string

False
location_id

The identifier of the location where this service is delivered.

string

False
name

The official or public name of the service.

string

True
alternate_name

Alternative or commonly used name for a service.

string

False
description

A description of the service.

string

False
url

URL of the service.

string

False
email

Email address for the service.

string

False
status

The current status of the service.

string

True
interpretation_services

A description of any interpretation services available for accessing this service.

string

False
application_process

The steps needed to access the service.

string

False
wait_time

Time a client may expect to wait before receiving a service.

string

False
accreditations

Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.

string

False
licenses

An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.

string

False
contacts/0/id

Each contact must have a unique identifier.

string

True
contacts/0/organization_id

The identifier of the organization for which this is a contact.

string

False
contacts/0/service_id

The identifier of the service for which this is a contact.

string

False
contacts/0/service_at_location_id

The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location.

string

False
contacts/0/name

The name of the person.

string

False
contacts/0/title

The job title of the person.

string

False
contacts/0/department

The department that the person is part of.

string

False
contacts/0/email

The email address of the person.

string

False
eligibility/0/id

Each entry must have a unique identifier.

string

True
eligibility/0/service_id

The identifier of the service for which this entry describes the eligibility criteria.

string

False
eligibility/0/eligibility

The rules or guidelines that determine who can receive the service.

string

False
fees/0/id

Each entry must have a unique identifier.

string

True
fees/0/service_id

The identifier of the service for which this entry describes the costs of service.

string

False
fees/0/fee

A listing of the costs of services, including free ones.

string

False
funding/0/id

Each entry must have a unique identifier.

string

True
funding/0/organization_id

The identifier of the organization for which this entry describes the source of funding.

string

False
funding/0/service_id

The identifier of the service for which this entry describes the source of funding.

string

False
funding/0/source

Source of funds for organization or service.

string

False
regular_schedule/0/id

Each entry must have a unique identifier.

string

True
regular_schedule/0/service_id

The identifier of the service for which this is the regular schedule.

string

False
regular_schedule/0/location_id

The identifier of the location for which this is the regular schedule.

string

False
regular_schedule/0/service_at_location_id

The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.

string

False
regular_schedule/0/weekday

The day of the week that this entry relates to.

string

True
regular_schedule/0/opens_at

The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.

string

False
regular_schedule/0/closes_at

The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.

string

False
holiday_schedule/0/id

Each entry must have a unique identifier.

string

True
holiday_schedule/0/service_id

The identifier of the service for which this is the holiday schedule.

string

False
holiday_schedule/0/location_id

The identifier of the location for which this is the holiday schedule.

string

False
holiday_schedule/0/service_at_location_id

The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.

string

False
holiday_schedule/0/closed

Indicates if a service or location is closed during a public holiday.

boolean

True
holiday_schedule/0/opens_at

The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.

string

False
holiday_schedule/0/closes_at

The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.

string

False
holiday_schedule/0/start_date

The first day that a service or location is closed during a public or private holiday.

string

True
holiday_schedule/0/end_date

The last day that a service or location is closed during a public or private holiday.

string

True
languages/0/id

Each language must have a unique identifier.

string

True
languages/0/service_id

The identifier of the service for which the entry describes the languages in which services are delivered.

string

False
languages/0/location_id

The identifier of the location for which the entry describes the languages in which services are delivered.

string

False
languages/0/language

Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes..

string

False
payment_accepted/0/id

Each entry must have a unique identifier.

string

True
payment_accepted/0/service_id

The identifier of the services for which the entry describes the accepted payment methods.

string

False
payment_accepted/0/payment

The methods of payment accepted for the service.

string

False
phones/0/id

Each entry must have a unique identifier.

string

True
phones/0/location_id

The identifier of the location where this phone number is located.

string

False
phones/0/service_id

The identifier of the service for which this is the phone number.

string

False
phones/0/organization_id

The identifier of the organisation for which this is the phone number.

string

False
phones/0/contact_id

The identifier of the contact for which this is the phone number.

string

False
phones/0/service_at_location_id

The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location.

string

False
phones/0/number

The phone number.

string

True
phones/0/extension

The extension of the phone number.

string

False
phones/0/type

Whether the phone number relates to a fixed or cellular phone.

string

False
phones/0/department

The department for which this is the phone number.

string

False
phones/0/language

A comma separated list of ISO 639-1, or ISO 639-2 [language codes](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities.

string

False
phones/0/description

A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times.

string

False
required_documents/0/id

Each document must have a unique identifier.

string

True
required_documents/0/service_id

The identifier of the service for which this entry describes the required document.

string

False
required_documents/0/document

The document required to apply for or receive the service. e.g. Government-issued ID, EU Passport.

string

False
service_area/0/id

Each service area must have a unique identifier.

string

True
service_area/0/service_id

The identifier of the service for which this entry describes the service area.

string

False
service_area/0/service_area

The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary.

string

False
service_area/0/description

A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields.

string

False