Introduction
Welcome to the SLQ Online Community Contribution API.
Spools
Get all spools
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/spools \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"spools": [
{
"slqIdentifier": "6169-1",
"contentDescription": "Photographs of selected houses in Walkervale.",
"photographCount": 7,
"photographSlqIdentifiers": [
"6169-1-1",
"6169-1-2",
"6169-1-3",
"6169-1-4",
"6169-1-5",
"6169-1-6",
"6169-1-7"
],
"localities": [
{
"id": 69,
"name": "Walkervale",
"geoLocation": {
"latitude": -24.8820498,
"longitude": 152.3596125
}
},
{
"id": 71,
"name": "Norville",
"geoLocation": {
"latitude": -24.8904492,
"longitude": 152.3450163
}
}
],
"imageUrls": [
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg"
]
}
]
}
Retrieves all spools.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/spools
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Get a specific spool
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/spools/6169-1004.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"slqIdentifier": "6169-1004",
"contentDescription": "Photographs of selected houses in Bundamba, Ipswich.",
"photographCount": 1,
"photographs": [
{
"slqIdentifier": "1-29-11",
"hasHumanTags": false,
"hasStories": false,
"address": {
"streetNumber": "662",
"streetName": "Dare",
"streetType": "Road",
"postcode": "4000",
"streetAddress": "662 Dare Road, Bundamba",
"localityName": "Bundamba"
},
"geoLocation": {
"latitude": 66.1157344573643,
"longitude": -152.685959479355
},
"imageUrl": "https://digital.slq.qld.gov.au/cantaloupe/iiif/2/IE315152:FL318105.jpg/full/128,/0/default.jpg",
"catalogUrl": "http://onesearch.slq.qld.gov.au/permalink/f/1upgmng/slq_alma21220400780002061"
}
],
"photographSlqIdentifiers": [
"6169-1004-0001",
],
"localities": [
{
"id": 99,
"name": "Bundamba",
"geoLocation": {
"latitude": -27.6048845,
"longitude": 152.8100289
}
}
]
}
Retrieves a specific spool.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/spools/:slq_identifier.json
URL Parameters
Parameter | Description |
---|---|
slq_identifier | The spool's SLQ identifier. |
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Localities
Get all localities
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/localities \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"localities": [
{
"id": 5,
"name": "Acacia Ridge",
"geoLocation": {
"latitude": -27.5857312,
"longitude": 153.025206
},
"spoolCount": 3,
"spools": [
{
"slqIdentifier": "6169-3271",
"photographCount": 20
},
{
"slqIdentifier": "6169-3272",
"photographCount": 27
},
{
"slqIdentifier": "6169-3274",
"photographCount": 14
}
]
}
]
}
Retrieves all localities.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/localities
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Tags
Get all tags
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/tags \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"tagTypes": [
"details",
"extras",
"fence",
"height",
"houseNum",
"roofMaterial",
"roofShape",
"wallMaterial"
],
"tagOptions": {
"details": [
{
"id": 203,
"name": "Brick fence"
},
{
"id": 297,
"name": "mailbox"
}
],
"extras": [
{
"id": 298,
"name": "letterboxes"
},
{
"id": 8,
"name": "concrete driveway"
},
{
"id": 9,
"name": "veranda"
}
]
}
}
Retrieves all tags, detailing types and selection options.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/tags
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Photographs
Get all photographs
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/photographs.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON (truncated here):
{
"photographs": [
{
"slqIdentifier": "6169-0010-0001",
"spoolSlqIdentifier": "6169-0010",
"address": null,
"geoLocation": null
},
{
"slqIdentifier": "6169-0001-0007",
"spoolSlqIdentifier": "6169-0001",
"address": null,
"geoLocation": null
},
{
"slqIdentifier": "6169-0010-0006",
"spoolSlqIdentifier": "6169-0010",
"address": null,
"geoLocation": null
}
],
"pagination": {
"page": 1,
"nextPage": 2,
"prevPage": null,
"perPage": 20,
"totalPages": 3068,
"totalResults": 61359
},
"aggregations": {
"tags": [
{
"tag": {
"id": 5,
"name": "Weatherboards",
"type": "wallMaterial"
},
"count": 565
},
{
"tag": {
"id": 4,
"name": "Corrugated Iron",
"type": "roofMaterial"
},
"count": 436
},
{
"tag": {
"id": 21,
"name": "Elevated",
"type": "height"
},
"count": 376
}
],
"spools": [
{
"spoolSlqIdentifier": "6169-1247",
"count": 68
},
{
"spoolSlqIdentifier": "6169-2200",
"count": 66
},
{
"spoolSlqIdentifier": "6169-0080",
"count": 53
}
],
"localities": []
}
}
The photographs index endpoint allows you to paginate through all photographs.
More importantly, it can be used to query for photographs using a number of different parameters.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/photographs.json?storied=true&order_by=storied_at&order_by_direction=desc
URL Parameters
Parameter | Description |
---|---|
query | A query string for searching for matching photographs. |
page | The page number for pagination, defaults to 1. |
per_page | The number of photographs to return per page. Maximum 100. |
has_geo_location | true/false Restrict results to photographs with or without geo location. |
human_tagged | true/false Restrict results to photographs that have been tagged by a person. |
is_shop | true/false Restrict results to photographs that are or are not shops. |
is_damaged | true/false Restrict results to photographs that are or are not damaged. |
has_house_name | true/false Restrict results to photographs with or without house names. |
has_annotations | true/false Restrict results to photographs with or without annotations. |
locality_ids | Restrict results to photographs in a particular locality or localities. Photographs from all localities provided will be returned. To request photographs from one locality, request photographs.json?locality_ids[]=5 . To request photographs from two localities, request photographs.json?locality_ids[]=5&locality_ids[]=14 . |
ordered_by | Order photographs. Valid values human_tagged_at, storied_at, or geo_located_at. |
spool_slq_identifiers | Restrict results to photographs in a particular spool, identified by its slq identifier. Photographs from all spools provided will be returned. To request photographs from one spool, request photographs.json?spool_slq_identifiers[]=6169-1041 . To request photographs from two spools, request photographs.json?spool_slq_identifiers[]=6169-1041&spool_slq_identifiers[]=6169-0001 . |
storied | Include stories for a photograph. Defaults to false. |
tag_ids | Restrict results to photographs having all tags provided. To request photographs tagged with one tag, request photographs.json?tags_ids[]=5 . To request photographs tagged with two tags, request photographs.json?tag_ids[]=5&tag_ids[]=14 . |
Aggregations
All responses return aggregations of the most popular tags, spools and localities within the result set of the query. For example, requesting photographs tagged with Weatherboard and Chain link will return the 20 most popular tags for photographs tagged with both those. count
is the number of photographs in each bucket.
Examples
Requesting photographs matching a query:
photographs.json?query=fence
query
matches against the following properties of photographs: SLQ identifier, spool SLQ identifier, spool content description, street number, street name, locality name, tag names.
Requesting photographs matching a query from a specific spool:
photographs.json?query=fence&spool_slq_identifiers[]=6169-1041
Requesting geo-located photographs with a specific tag in a specific locality:
photographs.json?tag_ids[]=5&locality_ids[]=14&has_geo_location=true
Errors
Should your query parameters fail validation, you will receive a 422 Unprocessable Entity
response, with an errors object. For example, the request photographs.json?per_page=500&has_geo_location=okay
, will return the error object displayed on the right.
{
"errors": {
"per_page": [
"must be less than or equal to 100"
],
"has_geo_location": [
"must be boolean"
]
}
}
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Get a specific photograph
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/photographs/6169-0642-0014.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"slqIdentifier": "6169-0642-0014",
"spoolSlqIdentifier": "6169-0642",
"address": null,
"geoLocation": null,
"tags": [
{
"id": 4,
"name": "Corrugated Iron",
"type": "roofMaterial"
},
{
"id": 5,
"name": "Weatherboards",
"type": "wallMaterial"
},
{
"id": 7,
"name": "Garage",
"type": "details"
},
{
"id": 19,
"name": "Metal railing",
"type": "details"
},
{
"id": 21,
"name": "Elevated",
"type": "height"
},
{
"id": 24,
"name": "Bay window",
"type": "details"
},
{
"id": 26,
"name": "Window awnings",
"type": "details"
},
{
"id": 39,
"name": "Car",
"type": "extras"
},
{
"id": 43,
"name": "Picket fence",
"type": "fence"
},
{
"id": 68,
"name": "Asymmetrical Bungalow",
"type": "roofShape"
},
{
"id": 112,
"name": "Dog",
"type": "extras"
}
],
"tagCollection": {
"roofMaterial": [
{
"id": 4,
"name": "Corrugated Iron"
}
],
"wallMaterial": [
{
"id": 5,
"name": "Weatherboards"
}
],
"details": [
{
"id": 7,
"name": "Garage"
},
{
"id": 19,
"name": "Metal railing"
},
{
"id": 24,
"name": "Bay window"
},
{
"id": 26,
"name": "Window awnings"
}
],
"height": [
{
"id": 21,
"name": "Elevated"
}
],
"extras": [
{
"id": 39,
"name": "Car"
},
{
"id": 112,
"name": "Dog"
}
],
"fence": [
{
"id": 43,
"name": "Picket fence"
}
],
"roofShape": [
{
"id": 68,
"name": "Asymmetrical Bungalow"
}
]
}
}
Retrieves a specific photograph.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/photographs/:slq_identifier.json
URL Parameters
Parameter | Description |
---|---|
slq_identifier | The photograph's SLQ identifier. |
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Get an untagged photograph
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/photographs/next-untagged.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"photograph": {
"slqIdentifier": "6169-1024-0020",
"spoolSlqIdentifier": "6169-1024",
"address": null,
"geoLocation": null,
"tags": [],
"tagCollection": {}
},
"untaggedCount": 60628
}
Retrieves an untagged photograph at random.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/photographs/next-untagged.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Get a tag cloud
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/photographs/tag-cloud.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"cloud": {
"wallMaterial": [
{
"tag": {
"id": 5,
"name": "Weatherboards",
"type": "wallMaterial"
},
"count": 208
},
{
"tag": {
"id": 18,
"name": "Brick",
"type": "wallMaterial"
},
"count": 74
}
],
"roofMaterial": [
{
"tag": {
"id": 4,
"name": "Corrugated Iron",
"type": "roofMaterial"
},
"count": 157
},
{
"tag": {
"id": 27,
"name": "Tile",
"type": "roofMaterial"
},
"count": 97
}
],
"height": [
{
"tag": {
"id": 21,
"name": "Elevated",
"type": "height"
},
"count": 143
},
{
"tag": {
"id": 2,
"name": "Single Storey",
"type": "height"
},
"count": 104
}
],
},
"taggedCount": 731,
"untaggedCount": 60628
}
Retrieves tag cloud in which tags are grouped by type.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/photographs/tag-cloud.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Tag a photograph
curl --request POST \
--url http://api.corley.slq.qld.gov.au/api/v1/photographs/1-13-269/taggings.json \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"tag_ids": [2, 7, 9],
"contributor_tags": "flag pole, palm tree, bay window"
}'
This endpoint returns this JSON:
{
"status": "ok"
}
Tag a photograph with official or contributor provided tags. This endpoint accepts a JSON body with tag information and tags the photograph identified in the URL.
The tags outlined in the JSON body are then appended to the tags of the photograph. The endpoint cannot be used to remove tags already associated with a photograph.
The JSON body should have the format as outlined on the right.
JSON body format:
{
"tag_ids": [2, 7, 9],
"contributor_tags": "flag pole, palm tree, bay window"
}
Your JSON body should exclude keys that do not have values rather than passing null values. You must provide either tags_ids
, contributor_tags
or both. Tag ids will be checked for validity.
HTTP Request
POST https://explorer-api.slq.qld.gov.au/api/v1/photographs/1-13-269/taggings.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
JSON body
Key | Value |
---|---|
tag_ids | An array of integer ids of the tags to apply to the photograph. These ids can be any ids returned by the tags endpoint or another tags source. |
contributor_tags | A string of custom tags identified by the contributor, comma separated. This value will be split on , with each value then trimmed of whitespace to produce Contributor tags. Contributor tags are not returned in the tags associated with individual photographs until they are promoted to an official tag type by an admin. |
Geolocate a photograph
curl --request PUT \
--url http://api.corley.slq.qld.gov.au/api/v1/photographs/1-25-0/geo-location.json \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"street_number": "5",
"street_name": "Albert",
"street_type": "Street",
"street_address": "5 Albert Street, Annerly QLD 4103",
"postcode": "4103",
"locality_name": "Annerly",
"state": "QLD",
"latitude": -27.52151015,
"longitude": 153.02954157
}'
This endpoint returns this JSON:
{
"status": "ok"
}
Geolocate a photograph using geolocation and address data. This endpoint accepts a PUT request with a JSON body with location and address information and geolocates the photograph identified in the URL.
The endpoint cannot be used to geolocate a photograph that already has a location.
The JSON body should have the format as outlined on the right.
JSON body format:
{
"street_number": "5",
"street_name": "Albert",
"street_type": "Street",
"street_address": "5 Albert Street, Annerly QLD 4103",
"postcode": "4103",
"locality_name": "Annerly",
"state": "QLD",
"latitude": -27.52151015,
"longitude": 153.02954157
}
Localities are matched to proper locality entities via case-insensitive comparison. Where localities do not exist, they are created.
An attempt to geo locate an already geolocated photograph will return 422 Unprocessable
.
HTTP Request
PUT https://explorer-api.slq.qld.gov.au/api/v1/photographs/1-13-269/geo-location.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
JSON body
Key | Value |
---|---|
street_number | The street number of the house. |
street_name | The street name. |
street_type | The type of street: Street, Road, Crescent etc. |
street_address | The full street address of the house. |
postcode | The house's postcode. |
locality_name | The name of a new or existing locality. |
state | The state the house is located in. |
latitude | The house's latitude. |
longitude | The house's longitude. |
All keys are mandatory.
Update a photograph
curl --request PUT \
--url http://api.corley.slq.qld.gov.au/api/v1/photographs/1-25-0.json \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '{
"house_name": "Carrington",
"annotations": "Owner interested to purchase",
"shop": false,
"damaged": true
}'
This endpoint returns this JSON:
{
"status": "ok"
}
Update a photograph by modifying a limited set of properties: house name, annotations, shop and damaged.
This is a PUT request. The JSON body should have the format as outlined on the right. The body may exclude properties is does not want to modify.
JSON body format:
{
"house_name": "Carrington",
"annotations": "Owner interested to purchase",
"shop": false,
"damaged": true
}
HTTP Request
PUT https://explorer-api.slq.qld.gov.au/api/v1/photographs/1-13-269.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
JSON body
Key | Value |
---|---|
house_name | The name of a house. |
annotations | Any annotations on the photograph. |
shop | true/false Whether the photograph depicts a shop. |
damaged | true/false Whether the photograph is damaged. |
All keys are optional.
Favourites
Get current favourite photographs
curl --request GET \
--url https://explorer-api.slq.qld.gov.au/api/v1/favourites.json \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"photographs": [
{
"slqIdentifier": "6169-0010-0001",
"spoolSlqIdentifier": "6169-0010",
"address": null,
"geoLocation": null
},
{
"slqIdentifier": "6169-0001-0007",
"spoolSlqIdentifier": "6169-0001",
"address": null,
"geoLocation": null
},
{
"slqIdentifier": "6169-0010-0006",
"spoolSlqIdentifier": "6169-0010",
"address": null,
"geoLocation": null
}
]
}
Retrieves the current contributor's list of favourite photographs. Newer favourites are listed first.
Making this request when a contributor is not signed in returns an empty array.
HTTP Request
GET https://explorer-api.slq.qld.gov.au/api/v1/favourites.json
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Add a favourite
curl --request POST \
--url 'https://explorer-api.slq.qld.gov.au/api/v1/favourites.json?slq_photograph_identifier=XXX' \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"status": "ok"
}
When a contributor is signed in:
Adds the photograph identified by the slq_photograph_identifier parameter to the contributor's list of favourites.
When a contributor is not signed in:
Adds an anonymous favourite for the photograph (for tracking/analytics purposes).
HTTP Request
POST https://explorer-api.slq.qld.gov.au/api/v1/favourites.json?slq_photograph_identifier=XXX
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Request parameters
Key | Value |
---|---|
slq_photograph_identifier | The identifier of the photograph to be favourited |
Remove a favourite
curl --request DELETE \
--url 'https://explorer-api.slq.qld.gov.au/api/v1/favourites.json?slq_photograph_identifier=XXX' \
--header 'accept: application/json' \
--header 'content-type: application/json'
This endpoint returns this JSON:
{
"status": "ok"
}
When a contributor is signed in:
Removes the photograph identified by the slq_photograph_identifier parameter from the contributor's list of favourites.
When a contributor is not signed in:
Returns a 422 Unprocessable
response.
HTTP Request
DELETE https://explorer-api.slq.qld.gov.au/api/v1/favourites.json?slq_photograph_identifier=XXX
Headers
Header | Value |
---|---|
Content-Type | application/json |
Accept | application/json |
Request parameters
Key | Value |
---|---|
slq_photograph_identifier | The identifier of the photograph to be unfavourited |