NAV
shell

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
shell