Skip to content
This repository has been archived by the owner on May 4, 2021. It is now read-only.

Commit

Permalink
Added image variants details
Browse files Browse the repository at this point in the history
  • Loading branch information
@toxuin
toxuin committed Jun 20, 2018
1 parent f2aaa2a commit 7754d15
Showing 1 changed file with 116 additions and 21 deletions.
137 changes: 116 additions & 21 deletions readme.md
View file
Expand Up @@ -4,6 +4,8 @@ First contact us to get an authentication token to access the API. Email us at a

Once the authentication token is recieved it must be sent in an http header called `X-muzooka-auth-token` for all requests to the API

In order to use the API, you need to accept and comply with [Muzooka Terms of Service](https://www.muzooka.com/m/legal). Making requests to the API is considered as an act of accepting those terms.

## Artist Lookup Endpoint

To lookup an artist, use their name or a portion of it for a fuzzy match. Use following endpoint:
Expand All @@ -29,9 +31,27 @@ Result would contain two top-level fileds: `data` and `pages`. `data` is an arra
"name": "Paul McCartney",
"banner": {
"smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/small.jpg",
"landscape1x1smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/1x1/small.jpg",
"landscape4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/4x3/small.jpg",
"landscape16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/16x9/small.jpg",
"landscape21x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/21x9/small.jpg",
"portrait4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/4x3/small.jpg",
"portrait16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/16x9/small.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/medium.jpg",
"landscape1x1mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/1x1/medium.jpg",
"landscape4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/4x3/medium.jpg",
"landscape16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/16x9/medium.jpg",
"landscape21x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/21x9/medium.jpg",
"portrait4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/4x3/medium.jpg",
"portrait16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/16x9/medium.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/large.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/original.jpg"
"landscape1x1largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/1x1/large.jpg",
"landscape4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/4x3/large.jpg",
"landscape16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/16x9/large.jpg",
"landscape21x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/landscape/21x9/large.jpg",
"portrait4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/4x3/large.jpg",
"portrait16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/portrait/16x9/large.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/124081/original.jpg",
},
"facebookUsername": "PaulMcCartney",
"city": "Liverpool",
Expand Down Expand Up @@ -86,10 +106,6 @@ The following endpoint returns the artists data
* `description`: Description of the artist
* `facebookUsername`: Artist's username on facebook. If artist does not have a username on facebook, artist's numeric facebook ID would be provided.
* `banner`: Banner image of the artist
* - `smallUrl`: Small version of the Banner
* - `mediumUrl`: Medium version of the Banner
* - `largeUrl`: Large version of the Banner
* - `original`: Original version of the Banner
* `socialLinks`: An array of social media links, only existing social links for the given artist will be included
* - `type`: Type of social media link (ex Twitter)
* - `id`: Social media id, username or profile
Expand All @@ -112,9 +128,27 @@ The following endpoint returns the artists data
"description": "'Songs of Experience' released Dec 1, pre-order now and listen to new song Get Out Of Your Own Way. eXPERIENCE + iNNOCENCE US Tour opens May. http://www.u2.com",
"banner": {
"smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/small.jpg",
"landscape1x1smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/1x1/small.jpg",
"landscape4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/4x3/small.jpg",
"landscape16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/16x9/small.jpg",
"landscape21x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/21x9/small.jpg",
"portrait4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/4x3/small.jpg",
"portrait16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/16x9/small.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/medium.jpg",
"landscape1x1mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/1x1/medium.jpg",
"landscape4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/4x3/medium.jpg",
"landscape16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/16x9/medium.jpg",
"landscape21x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/21x9/medium.jpg",
"portrait4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/4x3/medium.jpg",
"portrait16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/16x9/medium.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/large.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/original.jpg"
"landscape1x1largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/1x1/large.jpg",
"landscape4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/4x3/large.jpg",
"landscape16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/16x9/large.jpg",
"landscape21x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/landscape/21x9/large.jpg",
"portrait4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/4x3/large.jpg",
"portrait16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/portrait/16x9/large.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/40841/original.jpg",
},
"facebookUsername": "u2",
"socialLinks": [
Expand Down Expand Up @@ -256,38 +290,99 @@ The following endpoint returns the images for the artist

`GET` `https://api.muzooka.com/artists/:facebookUsername/images`

Muzooka API provides 3 fixed-width resized version of the original image, along with the original image. Muzooka images are not crops, just resizes – so only the width is of knows size and aspect ratio is preserved of the original image. This applied to all images across the API, not just to this endpoint.
Muzooka API provides multiple variants of every image. There are two variant types: a resize and a crop. Resize has the same aspect ratio as the original image, whereas crops have standard aspect ratios. This applies to all images across the API, not just to this endpoint.

Currently, Muzooka supports following aspect ratios:
- `1x1`
- `4x3`
- `16x9`
- `21x9`

Common sizes used throughout the API are `small`, `medium`, `large` and `original`. Here is a size chart:
Each crop variant can be presented in either `landscape` or `portrait` orientation. Square images (`1x1`), by convention, do not have a `portrait` variant. Also there is no `portrait` orientation for `21x9`.

- `small`: 320 px wide.
- `medium`: 768 px wide.
- `large`: 1200 px wide.
There are 4 standard sizes, along with the original image, that Muzooka API serves:
- `small`: 320x240 in `4x3`, 320x180 in `16x9`, 320x135 in `21x9`
- `medium`: 768x576 in `4x3`, 768x432 in `16x9`, 768x324 in `21x9`
- `large`: 1280x960 in `4x3`, 1280x720 in `16x9`, 1280x540 in `21x9`
- `original`: original image as initally uploaded.

### Response Structure
Array of:
- `id`: Muzooka image Id
- `smallUrl`: The url for the small image
- `mediumUrl`: The url for the large image
- `largeUrl`: The url for the large image
- `original`: The url for the original image
- `id`: Muzooka image Id
- `smallUrl`: A small resize of the original image with aspect ratio preserved
- `landscape1x1smallUrl`: Landscape crop with 1x1 aspect ratio, 320x320
- `landscape4x3smallUrl`: Landscape crop with 4x3 aspect ratio, 320x240
- `landscape16x9smallUrl`: Landscape crop with 16x9 aspect ratio, 320x180
- `landscape21x9smallUrl`: Landscape crop with aspect ratio, 320x135
- `portrait4x3smallUrl`: Portrait crop with 4x3 aspect ratio, 240x320
- `portrait16x9smallUrl`: Portrait crop with 16x9 aspect ratio, 180x320
- `mediumUrl`: A medium resize of the original image with aspect ratio preserved
- `landscape1x1mediumUrl`: Landscape crop with 1x1 aspect ratio, 768x768
- `landscape4x3mediumUrl`: Landscape crop with aspect ratio, 768x576
- `landscape16x9mediumUrl`: Landscape crop with 16x9 aspect ratio, 768x432
- `landscape21x9mediumUrl`: Landscape crop with aspect ratio, 768x324
- `portrait4x3mediumUrl`: Portrait crop with 4x3 aspect ratio, 576x768
- `portrait16x9mediumUrl`: Portrait crop with 16x9 aspect ratio, 432x768
- `largeUrl`: A large resize of the original image with aspect ratio preserved
- `landscape1x1largeUrl`: Landscape crop with 1x1 aspect ratio, 1280x1280
- `landscape4x3largeUrl`: Landscape crop with 4x3 aspect ratio, 1280x960
- `landscape16x9largeUrl`: Landscape crop with 16x9 aspect ratio, 1280x720
- `landscape21x9largeUrl`: Landscape crop with aspect ratio, 1280x540
- `portrait4x3largeUrl`: Portrait crop with 4x3 aspect ratio, 960x1280
- `portrait16x9largeUrl`: Portrait crop with 16x9 aspect ratio, 720x1280
- `original`: The original uploaded image

### Example Response
```json
[
{
"id": "123",
"smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/small.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/medium.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/large.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/original.jpg"
"landscape1x1smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape1x1smallUrl.jpg",
"landscape4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape4x3smallUrl.jpg",
"landscape16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape16x9smallUrl.jpg",
"landscape21x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape21x9smallUrl.jpg",
"portrait4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait4x3smallUrl.jpg",
"portrait16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait16x9smallUrl.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/mediumUrl.jpg",
"landscape1x1mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape1x1mediumUrl.jpg",
"landscape4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape4x3mediumUrl.jpg",
"landscape16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape16x9mediumUrl.jpg",
"landscape21x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape21x9mediumUrl.jpg",
"portrait4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait4x3mediumUrl.jpg",
"portrait16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait16x9mediumUrl.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/largeUrl.jpg",
"landscape1x1largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape1x1largeUrl.jpg",
"landscape4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape4x3largeUrl.jpg",
"landscape16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape16x9largeUrl.jpg",
"landscape21x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/landscape21x9largeUrl.jpg",
"portrait4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait4x3largeUrl.jpg",
"portrait16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/portrait16x9largeUrl.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/33111/original.jpg",
},
{
"id": "456",
"smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/small.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/medium.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/large.jpg",
"landscape1x1smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape1x1smallUrl.jpg",
"landscape4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape4x3smallUrl.jpg",
"landscape16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape16x9smallUrl.jpg",
"landscape21x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape21x9smallUrl.jpg",
"portrait4x3smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait4x3smallUrl.jpg",
"portrait16x9smallUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait16x9smallUrl.jpg",
"mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/mediumUrl.jpg",
"landscape1x1mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape1x1mediumUrl.jpg",
"landscape4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape4x3mediumUrl.jpg",
"landscape16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape16x9mediumUrl.jpg",
"landscape21x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape21x9mediumUrl.jpg",
"portrait4x3mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait4x3mediumUrl.jpg",
"portrait16x9mediumUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait16x9mediumUrl.jpg",
"largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/largeUrl.jpg",
"landscape1x1largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape1x1largeUrl.jpg",
"landscape4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape4x3largeUrl.jpg",
"landscape16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape16x9largeUrl.jpg",
"landscape21x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/landscape21x9largeUrl.jpg",
"portrait4x3largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait4x3largeUrl.jpg",
"portrait16x9largeUrl": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/portrait16x9largeUrl.jpg",
"original": "https://d1vuu6jk2dpw02.cloudfront.net/images/33631/original.jpg",
}
]
Expand Down

0 comments on commit 7754d15

Please sign in to comment.