Images
Image Object
This collection of endpoints deal with images. We provide a JSON Schema for the image object, which you can find here. You can use the schema to validate the JSON structure of any returned image data.
The following basic details are always included with the image object, whether fetching a paginated list of images or a single image:
{
"data": {
"id": "6609e31c...", // The ID of the image resource
"organisation_id": "1c862f0a...", // The ID of the organisation that owns the image
"title": "Image Title...", // The image title
"caption": "Image Caption...", // The image capation
"dimensions": { // The dimensions of the original image
"width": 100,
"height": 100
},
"filesize": 12345, // The image file size in bytes
"meta": { // Any arbitrary imformation attached to the image
"Driver": "Driver",
"Co-Driver": "Co-Driver",
},
"links": {
"view": "https://...", // The link to the image in the MotorPress UI
"thumbnail": {
"square": "https://...", // A signed URL to a square thumbnail
"landscape": "https://...", // A signed URL to a landscape thumbnail
"portrait": "https://..." // A signed URL to a portrait thumbnail
},
"web": "https://...", // A signed URL to a web ready version of the image
"download": "https://..." // A signed URL to download the original image
},
"created_at": "2023-..." // The date and time the image was uploaded
}
}
Fetch Images
OrganisationUserYou can retrieve a list of public images ordered by the upload date. Images marked as private are not included.
This endpoint returns a paginated response.
Endpoint
URL Parameters
The only URL parameter accepted is the private flag. This is only available when using an organisation token for authentication.
| Parameter | Description |
|---|---|
| private | A boolean flag to include private images in the index. By default private images are not included. This parameter is only available when authenticated as an organisation. |
curl "https://api.motorpress.co.za/images?private=1" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer TEST_TOKEN'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.motorpress.co.za/images?private=1');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Accept: application/json',
'Content-Type: application/json',
'Authorization: Bearer TEST_TOKEN',
]);
$response = curl_exec($ch);
if (!$response) {
die('Error: "' . curl_error($ch) . '" - Code: ' . curl_errno($ch));
}
echo 'HTTP Status Code: ' . curl_getinfo($ch, CURLINFO_HTTP_CODE) . PHP_EOL;
echo 'Response Body: ' . $response . PHP_EOL;
curl_close($ch);
{
"data": [
{
"id": "394db698-2088-4671-8eba-3afb9a9667f1",
"organisation_id": "1c862f0a-6a3d-446d-bfdc-fe76870dc1ca",
"title": "velit et vel",
"caption": "Cum magnam exercitationem minus quae fugiat magnam. Cumque pariatur iure eligendi illo et necessitatibus debitis. Et at soluta et libero placeat voluptas.",
"dimensions": {
"width": 1800,
"height": 1300
},
"filesize": 304124,
"meta": {
"Driver": "Marjolaine Lakin",
"Co-Driver": "Mr. Bell Macejkovic"
},
"links": {
"view": "https://motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1",
"thumbnail": {
"square": "https://api.motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1.jpg?expires=1708281841&thumb=1&signature=6a1d32bebaf4e0069e456ac69199f1737951fe2de4465e845dc842c7bf64f720",
"portrait": "https://api.motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1.jpg?expires=1708281841&orientation=p&thumb=1&signature=dde76d7fe44a6017e91630c711eb062f7f886923304b8237c7aa46d7d2c8b2e3",
"landscape": "https://api.motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1.jpg?expires=1708281841&orientation=l&thumb=1&signature=d03d29f590e31d7291810f802a33e582b76db0401b0636291997b3d27b60ffda"
},
"web": "https://api.motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1.jpg?expires=1708281841&signature=055a54bf09a27a2f1265d9518ad9610a9e69a575340a41f6dc6af00e008ab8e7",
"download": "https://api.motorpress.co.za/images/394db698-2088-4671-8eba-3afb9a9667f1/download?expires=1708281841&signature=f25501677309993dd516d857d8870eb8def182cb3c39b0d28fdf4f8b375925b8"
},
"created_at": "2024-02-13T14:32:46+00:00"
}
//...
],
"links": {
"first": "https://api.motorpress.co.za/images?page=1",
"last": "https://api.motorpress.co.za/images?page=7",
"prev": null,
"next": "https://api.motorpress.co.za/images?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 7,
"links": [
{
"url": null,
"label": "« Previous",
"active": false
},
{
"url": "https://api.motorpress.co.za/images?page=1",
"label": "1",
"active": true
},
{
"url": "https://api.motorpress.co.za/images?page=2",
"label": "2",
"active": false
},
// ...
{
"url": "https://api.motorpress.co.za/images?page=2",
"label": "Next »",
"active": false
}
],
"path": "https://api.motorpress.co.za/images",
"per_page": 20,
"to": 20,
"total": 127
}
}
Fetcing a Single Image
OrganisationUserIf you need to fetch the data of a single image, you can use this endpoint. However, it's important to note that the data returned by this endpoint is no different from the data returned when fetching a paginated list of images. This is only really useful when you already know the ID of the image you want to fetch.
Endpoint
Signed Image URLs
The MotorPress API allows you to fetch image binary data directly. However, it is strongly recommended that you cache image data in your own application as requests to these endpoints still count towards the rate limit. In addition, the URLs found in the image objects are signed and are only valid for 12 hours. Attempting to fetch an expired URL will result in a 403 HTTP response.
Image responses are cached on the server side. This is done to reduce the strain and bandwidth demand on our infrastucture. If an image is changed through MotorPress, the cache will be automatically invalidated and you'll be able to fetch a fresh image.
Scaling images
The MotorPress API provides a few tools for scaling images within the request. This can be done by passing a width or height URL parameter. If you pass both width and height the image will be scaled and cropped accordingly.
| Parameter | Value | Description |
|---|---|---|
| width | number | Scale the image to the specified width. |
| height | number | Scale the image to the specified height. |
| scale | number | Scale the image to the specified percentage of it's original size. |
| thumb | boolean/string | Return a thumbnail of the image. By default a square thumbnail is returned. Use a value of p or l to change the orientation. |
| signature | string | The required signature for the image. Protects against hot linking abuse |
You can change width, height, scale, or thumb parameters without worrying about the required signature
To scale an image proportionately, use either width OR height, or scale:
/images/1234567890.jpg?width=500&signature=...
/images/1234567890.jpg?height=800&signature=...
/images/1234567890.jpg?scale=50&signature=...
Scale and crop an image to a pre-determined size. Note that the crop is always centered.
/images/1234567890.jpg?width=500&height=400&signature=...
No scaling up
You cannot scale an image above it's original dimensions. For example, scale=200 would simply return the original image at 100%. You also cannot use width=5000 if the image is only 3000 pixels wide. MotorPress will always default back to the original image dimensions as the maximum. Note that no error is returned if you do attempt to scale an image up.
Thumbnails
The MotorPress UI makes used of square thumbnails. However, this might not be ideal for your use case, you can request either landscape or portrait thumbnails. If you need very specific thumbnails, you can make use of the scaling options above to define your own thumbnail size. However, make sure to cache the result within your own app as each request counts towards the rate limit.
By default passing any value except p or l will return a square thumbnail. However, passing a value of p will return a portrait thumbnail and l a landscape thumbnail.
/images/IMAGE_UUID.jpg?thumb=p