GET/v1/places
Access Victoria Heritage Database records for all land based heritage sites in Victoria.
Explore Victoria’s heritage
A connection to
A connection to
Victoria’s past.
Search heritage places and shipwrecks, discover their stories, and build with records from the Victorian Heritage Database.
BASE URL
https://api.heritagecouncil.vic.gov.au/v1Read-only access · HAL JSON responses · No API key required
Your first request
Send a GET request to a resource under /v1/. Use the Accept header below to request HAL JSON.
curl -H 'Accept: application/hal+json' \
'https://api.heritagecouncil.vic.gov.au/v1/places?kw=abbotsford&rpp=10'Search a collection
Combine keyword, location and heritage filters. Results include pagination links, facets and spelling suggestions.
Try a place search →Read a record
Append the numeric record ID to retrieve details, including descriptions, images and related information.
View /v1/places/1 →Use the
/v1 prefix in integrations. Unversioned URLs are also supported. The legacy Accept: application/vnd.vhd.v1+json media type is accepted. HEAD and OPTIONS are supported; write methods are rejected.Follow the links
Responses use HAL JSON (application/hal+json). Collections place records inside _embedded; _links provides URLs for the current resource and available pages.
{
"_links": {
"self": {
"href": "https://api.heritagecouncil.vic.gov.au/v1/places?rpp=10&page=1"
},
"next": {
"href": "https://api.heritagecouncil.vic.gov.au/v1/places?rpp=10&page=2"
}
},
"_embedded": {
"places": [
{
"id": 1,
"name": "Example heritage place",
"_links": {
"self": {
"href": "https://api.heritagecouncil.vic.gov.au/v1/places/1"
}
}
}
]
},
"page_count": 2,
"page_size": 10,
"total_items": 12
}Illustrative response, abbreviated to show one record and two links; this is not live data.
Pagination starts at page=1. Place and shipwreck searches default to 25 records per page; set rpp between 1 and 1000. Themes use 25 records per page. Follow first, last, prev and next when present. Empty results have page_count: 0.
Lookup collections use their legacy embedded names, such as heritage_authority and local_government_authority. IDs may be strings or numbers. Some optional fields are null, and empty nested data may be an empty array.
Search responses also include facets with IDs, labels and counts, and spelling_suggestion. Place facets group secondary themes and categories beneath their primary entries.
Places detail fields
idnamelocationsignificancesignificance_updated_atstatusvhr_numberhi_numbercitationextent_of_registrationexempt_policylongitudelatitudehistorical_notescomparisonsheritage_inventory_descriptionprecinct_nameheritage_authority_nameheritage_authority_briefheritage_authority_idregistered_onregistration_last_amended_onconstructionother_namesdescriptionsinventory_site_detailsimagesaddressesmunicipalitiespermit_exemptionsattachmentsprimary_themesprimary_categoriesoverlay_numbersheritage_studiesarchitectsarchitectural_stylesheritage_act_categoriesplacesheritage_study_placeShipwrecks detail fields
idnamesignificancelocationlengthbreadthdepthbuilderbuilt_countrybuilt_yearbuilt_portcargocrewcrew_numberclassificationdate_lostyear_lostdestinationdepartureengine_builderengine_specificationhow_lostmastership_numberpassengerspassenger_numberownerregistration_numberregistration_countryregistration_former_detailsregistration_portvhr_historyhullpropulsionconstruction_materialrigweatheralternative_namesprimary_usessecondary_usesimagesheritage_authority_nameheritage_authority_briefvhr_numbermastEndpoints
All paths below are relative to this host. Open a collection to inspect its response, or use a numeric ID where a detail route is available.
GET/v1/shipwrecks
Retrieve a paginated list of Victorian Heritage Database records of shipwrecks. Pass in a shipwreck id to fetch all information on a specific shipwreck.
GET/v1/themes
Heritage listed places can be filtered by themes and sub-themes. Use this endpoint to retrieve the list of available themes, pass in a theme id to retrieve it's sub-themes.
GET/v1/municipalities
Victorian Heritage Database records can be filtered by municipality. Use this endpoint to retrieve a list of available municipalities.
GET/v1/architectural-styles
Heritage listed places can be filtered by Architectural style (eg Victorian Period (1851-1901) Second Empire). Use this endpoint to retrieve a list of architectural styles available.
GET/v1/heritage-act-categories
Heritage listed places can be filtered by act categories. Use this endpoint to retrieve a list of available heritage act categories.
GET/v1/categories
Heritage listed places can be filtered by category and sub category (eg Cemeteries and Burial Sites : Headstone). Use this endpoint to retrieve a list of available categories. Pass in a category id to retrieve a list of that category's sub categories.
GET/v1/ship-propulsions
Shipwrecks can be filtered by propulsion type (eg - sail). Use this endpoint to retrieve a list of available propulsion types.
GET/v1/ship-rigs
Shipwrecks can be filtered by rig type (eg - Ketch). Use this endpoint to retrieve a full list of available rig types.
GET/v1/ship-primary-uses
Shipwrecks can be filtered by primary use (eg - Fisheries). Use this endpoint to retrieve a complete list of available primary uses
GET/v1/ship-secondary-uses
Shipwrecks can be filtered by secondary uses (eg - Harbour Recreation). Use this endpoint to retrieve a list of secondary uses
GET/v1/architects
Heritage listed places can be filtered by architect. Use this endpoint to get the complete list of available architects
GET/v1/periods
Heritage listed places can filtered by 5 year periods. Use this endpoint to get the list of available 5 year periods. Note that only 5 year periods that have records will be returned so gaps in the timeline is to be expected.
GET/v1/ship-periods-built
Shipwrecks can be filtered by 5 year periods for the year built. Use this endpoint to retrieve a list of available 5 year periods for the year a ship was built.
GET/v1/ship-construction-materials
Shipwrecks can filtered by construction material (eg - wood). Use this endpoint to retrieve a full list of available construction materials
GET/v1/heritage-authorities
A Heritage Authority is a body responsible for a heritage listing. Authorities are Heritage Victoria, Heritage Inventory, a Local Government Authority, Vic. War Heritage Inventory or National Trust.
Add hasListings=true to return authorities with place listings.
GET/v1/recommended-tours
Heritage Victoria provides some select tours or groups of places in proximity to each other that share a common theme. This endpoint provides access to these recommended tours.
Use limit (1–100) to limit the tour list. A tour detail includes its places.
GET/v1/places-collection
In addition to searching places using the /places endpoint you can retrieve a predetermined collection of places by passing in an array of place ID's using the col[] parameter.
col is required: up to 100 numeric IDs, comma-separated or supplied as col[]=1&col[]=2. Indexed arrays such as col[0]=1 also work.
GET/v1/shipwrecks-collection
In addition to searching shipwrecks via the /shipwrecks endpoint you can retrieve a collection of shipwrecks via the /shipwrecks-collection endpoint by passing an array of shipwreck id's. e.g: /shipwrecks-collection?col[]=1&col[]=2
col is required: up to 100 numeric IDs, comma-separated or supplied as col[]=1&col[]=2. Indexed arrays such as col[0]=1 also work.
GET/v1/autocomplete
The autocomplete endpoint provides a "suggest" feature for keyword search fields. Suggested words are drawn from names and locations of places and shipwrecks.
GET/v1/ship-periods-lost
Shipwrecks can be filtered by 5 year periods for the date lost. Use this endpoint to retrieve the list of available 5 year periods for date lost.
Place search
Combine parameters with & and URL-encode values. Numeric filter IDs come from the corresponding lookup endpoints.
| Parameter | Description | Example request |
|---|---|---|
page | Page number, starting at 1 (default 1). | /v1/places?page=2 |
rpp | Records per page: 1–1000, default 25. | /v1/places?rpp=10 |
kw | Keyword search. Searches numerous fields for matches | /v1/places?kw=some+words |
kwt | Keyword search type. Used conjunction with keyword search to define the search as either one(at least one of the words), all(all words, any order) or exact(exact match) | /v1/places?kw=some+keywords&kwt=one |
kwe | Words to exclude from keyword search | /v1/places?kw=some+keywords&kwe=words+to+exclude |
aut | Heritage authority. Numerical ID. The IDs and names of heritage authorities can be retrieved from the /heritage-authorities API endpoint | /v1/places?aut=2 |
sub | Suburb | /v1/places?sub=glenlyon |
str | Street | /v1/places?str=brunswick+street |
mun | Municipality. Numerical ID. The IDs and names of municipalities can be retrieved from the /municipalities API endpoint | /v1/places?mun=4 |
pos | Postcode | /v1/places?pos=3056 |
add | Address | /v1/places?add=39+nicholson+street+abbotsford+yarra+city |
arc | Architect | /v1/places?arc=davidson |
arcs | Architectural Style. Numerical ID. The IDs and names of architectural styles can be retrieved from the /architectural-styles API endpoint | /v1/places?arcs=3 |
yc_min | Year of construction minimum. Use in conjunction with yc_max to form a range | /v1/places?yc_min=1890 |
yc_max | Year of construction maximum. Use in conjunction with yc_min to form a range | /v1/places?yc_max=1920 |
tp | Primary theme. Numerical ID. The IDs and names of themes can be retrieved from the /themes API endpoint | /v1/places?tp=2 |
ts | Secondary theme. Numerical ID. The IDs and names of secondary themes are a property of individual primary themes and can be fetched at the /themes/<theme_id> API endpoint | /v1/places?ts=4 |
cp | Primary category. Numerical ID. The IDs and names of primary categories can be retrieved from the /categories API endpoint | /v1/places?cp=4 |
cs | Secondary category. Numerical ID. The IDs and names of secondary categories are a property of individual primary categories and can be fetched at the /categories/<category_id> API endpoint | /v1/places?cs=2 |
cat | Heritage act categories. Numerical ID. The IDs and names of heritage act categories can be retrieved from the /heritage-act-categories API endpoint | /v1/places?cat=3 |
per | Time period. Numerical ID. The IDs and year ranges of time periods can be retrieved from the /periods API endpoint | /v1/places?per=4 |
nme | Name | /v1/places?nme=dights+mill |
nmf | Former name | /v1/places?nmf=the+grange |
his | History. Keyword search on the historical information of a place | /v1/places?his=some+keywords |
idn | Identifier. Use idnt=hermes (default) for a place ID, vhr for a VHR number, hi for a Heritage Inventory number, or ho for an overlay number. | /v1/places?idn=H1522&idnt=vhr |
geo | Places within a radius: latitude,longitude,distance in kilometres. A bounding box also accepts lat1,lon1,lat2,lon2. | /v1/places?geo=-37.803030,145.004620,1 |
sort | Sort results by name ascending or name descending (az or za), construction date asc or desc (dta or dtd) or by VHR number asc or desc (vna or vnd). Send empty sort value to reset to default relevance sorting | /v1/places?sort=az |
collapse | Occasionally places will have multiple records under different heritage authorities. Use this parameter to force records to be collapsed under a primary record or listed individually. | /v1/places?collapse=true |
idnt | Identifier type: hermes, vhr, hi or ho. | /v1/places?idn=H1522&idnt=vhr |
The architectural style filter also accepts the website’s structured facet form:
arcs[id]=46&arcs[name]=Style. The ID is used for filtering. Set collapse=true to group records for the same place.Shipwreck search
Combine parameters with & and URL-encode values. Numeric filter IDs come from the corresponding lookup endpoints.
| Parameter | Description | Example request |
|---|---|---|
page | Page number, starting at 1 (default 1). | /v1/shipwrecks?page=2 |
rpp | Records per page: 1–1000, default 25. | /v1/shipwrecks?rpp=10 |
kw | Keyword search. Searches numerous fields for matches | /v1/shipwrecks?kw=some+keywords |
kwt | Keyword search type. Used conjunction with keyword search to define the search as either one(at least one of the words), all(all words, any order) or exact(exact match) | /v1/shipwrecks?kw=some+keywords&kwt=one |
kwe | Words to exclude from keyword search | /v1/shipwrecks?kw=some+keywords&kwe=words+to+exclude |
nme | Ship name, case insensitive | /v1/shipwrecks?nme=agnes |
num | Official ship number | /v1/shipwrecks?num=152168 |
ll | Location lost | /v1/shipwrecks?ll=port+arthur |
yb_min | Year built minimum, use in conjunction with yb_max to form a range | /v1/shipwrecks?yb_min=1885 |
yb_max | Year built maximum, use in conjunction with yb_min to form a range | /v1/shipwrecks?yb_max=1910 |
yl_min | Year lost minimum, use in conjunction with yl_max to form a range | /v1/shipwrecks?yl_min=1885 |
yl_max | Year lost maximum, use in conjunction with yl_min to form a range | /v1/shipwrecks?yl_max=1910 |
dpp | Departure port | /v1/shipwrecks?dpp=sydney |
dsp | Destination port | /v1/shipwrecks?dsp=melbourne |
pc | Passenger and crew names | /v1/shipwrecks?pc=McMillen |
cgo | Cargo description | /v1/shipwrecks?cgo=timber |
plb | Place the ship was built | /v1/shipwrecks?plb=hobart+tasmania |
plr | Place the ship was registered | /v1/shipwrecks?plr=hobart+tasmania |
pro | Propulsion type. Numerical ID. The IDs and names of propulsion types can be retrieved from the /ship-propulsions API endpoint | /v1/shipwrecks?pro=3 |
rig | Rig. Numerical ID. The IDs and names of rig types can be retrieved from the /ship-rigs API endpoint | /v1/shipwrecks?rig=1 |
vup | Primary vessel usage. Numerical ID. The IDs and names of options can be retrieved from the /ship-primary-uses API endpoint. | /v1/shipwrecks?vup=2 |
vus | Secondary vessel usage. Numerical ID. The IDs and names of options can be retrieved from the /ship-secondary-uses API endpoint | /v1/shipwrecks?vus=4 |
cm | Construction material. Numerical ID. The IDs and names of options can be retrieved from the /ship-construction-materials API endpoint | /v1/shipwrecks?cm=2 |
pco | Period the ship was constructed. Numerical ID. The IDs and year ranges can be retrieved from the /ship-periods-built API endpoint | /v1/shipwrecks?pco=3 |
pl | Period the ship was lost. Numerical ID. The IDs and year ranges can be retrieved from the /ship-periods-lost API endpoint | /v1/shipwrecks?pl=2 |
sort | Sort results by name ascending or name descending (az or za). Send empty sort value to reset to default relevance sorting | /v1/shipwrecks?sort=az |
numt | Use hermes to search a shipwreck registry number. | /v1/shipwrecks?num=12&numt=hermes |
Autocomplete
Supply a required keyword (kw) and an optional dictionary (dic, default kw).
GET /v1/autocomplete?kw=abbot&dic=kw| Dictionary | Searches |
|---|---|
kw | Keywords |
add | Place locations |
sub | Suburbs |
str | Streets |
ll | Shipwreck locations |
arc | Architects |
dpp | Departure ports |
nmf | Former names |
plb | Places built |
plr | Places registered |
nme | Names |
Errors & limits
API errors return application/problem+json with type, title, status and detail. Check the HTTP status before reading a success payload.
{
"type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
"title": "Bad Request",
"status": 400,
"detail": "rpp must be an integer between 1 and 1000"
}| Status | Meaning |
|---|---|
| 400 | Invalid parameters or missing required input. |
| 404 | Resource or record not found. |
| 405 | Unsupported request method. |
| 406 | Unsupported Accept media type. |
| 502 | The search service returned an error or an invalid response. |
| 503 | A required database or search service is unavailable. |
Query values are limited to 2000 characters. Nested inputs are accepted only for the documented style facet and collection IDs. Pagination values must be positive integers. Public API responses allow cross-origin access.
The /up health check confirms the application boots; it does not test database or search availability.