getLocationPhoto

POST public/getLocationPhoto

Returns one photo for a location, with the full-size image base64-encoded.

Request syntax

curl https://apiv2.acumera.net/public/getLocationPhoto \
  --cookie av_session.txt \
  --data-urlencode "location_id=<location_id>" \
  --data-urlencode "filename=<stored_filename>"

The username, password, and tfa_token parameters are also accepted, and are required only if the client hasn't already signed in with login. See Getting started with the SC//AcuVigil API.

Request parameters

The request accepts the following parameters in a form-encoded body.

Parameter	Type	Description	Required	Default value
`location_id`	Integer	The ID of the location the photo belongs to.	Yes
`filename`	String	The photo's stored filename, exactly as getLocationPhotos returns it, for example `rack_1793398093.png`.	Yes

Response syntax

{
    "success": "string",
    "data": {
        "location_photo": {
            "id": "string",
            "filename": "string",
            "thumbnail_filename": "string",
            "description": "string",
            "created": "string",
            "created_by": "string",
            "created_by_name": "string",
            "editable": number,
            "content_length": "string",
            "content_type": "string",
            "image_content": "string"
        }
    }
}

Response parameters

If the call succeeds, success is "1" and location_photo is returned. It has the same fields as each photo in getLocationPhotos, and always includes the image:

Field	Description
`content_length`	The full-size image's size in bytes.
`content_type`	The image's MIME type, for example `image/png`.
`image_content`	The full-size image, base64-encoded.

Errors

If the call fails, success is "0", and returnCode and returnMessage describe the problem. The HTTP status is still 200.

Return code	Message	Cause
`NO_LOCATION_SELECTED`	No location was selected or the location does not exist.	`location_id` is missing or isn't a number.
`LOCATION_NOT_FOUND`	The location was not found.	No location has that ID.
`AUTH_FAILED_FUNC_NOT_ALLOWED`	Authorization failed because you are not permitted to access the requested function.	Your account doesn't have access to the location.
`MISSING_FILENAME`	No filename supplied.	`filename` is missing or empty.
`IMAGE_NOT_FOUND`	The image cannot be located.	The location has no photo with that stored filename.
`INVALID_LOGIN`	We were unable to log you in. Make sure you entered the correct username, password and 2FA code.	You haven't signed in, your session has ended, or the credentials sent with the call are wrong.

Examples

Example: Get a photo

curl https://apiv2.acumera.net/public/getLocationPhoto \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "filename=rack_1793398093.png"

Response (image_content shortened):

{
    "success": "1",
    "data": {
        "location_photo": {
            "id": "19130",
            "filename": "rack_1793398093.png",
            "thumbnail_filename": "rack_1793398093_.png",
            "description": "Network rack",
            "created": "1793398093",
            "created_by": "1001",
            "created_by_name": "Pat Example",
            "editable": 1,
            "content_length": "1827",
            "content_type": "image/png",
            "image_content": "iVBORw0KGgoAAAANSUhEUgAAAFUAAAA4CAYAAACMn7Te..."
        }
    }
}

To save the image, decode image_content from base64. For example, with jq:

curl -s https://apiv2.acumera.net/public/getLocationPhoto \
  --cookie av_session.txt \
  --data-urlencode "location_id=4510" \
  --data-urlencode "filename=rack_1793398093.png" \
  | jq -r '.data.location_photo.image_content' | base64 --decode > rack.png

Example: Use the original filename instead of the stored filename

{
    "success": "0",
    "returnCode": "IMAGE_NOT_FOUND",
    "returnMessage": "The image cannot be located."
}