Feeds v2 Migration Guide

This guide will help you update your existing code to the new v2 JSON feeds format.

Breaking changes

1. New JSON structure for basic feeds

Basic source feeds now return an object instead of an array. The array of posts that was previously directly returned has been moved to the posts property.

2. `Media` → `Posts`

In v1 advanced source feeds (which already returned an object) the array of posts was under the media property. In v2 this has been renamed to posts.

[
  {
    "id": "18195958162174903",
    "caption": "Example post 1"
  },
  {
    "id": "18195958162174904",
    "caption": "Example post 2"
  },
  {
    "id": "18195958162174905",
    "caption": "Example post 3"
  }
]

{
  "media": [
    {
      "id": "18195958162174903",
      "caption": "Example post 1"
    },
    {
      "id": "18195958162174904",
      "caption": "Example post 2"
    },
    {
      "id": "18195958162174905",
      "caption": "Example post 3"
    }
  ]
}

{
  "posts": [
    {
      "id": "18195958162174903",
      "caption": "Example post 1"
    },
    {
      "id": "18195958162174904",
      "caption": "Example post 2"
    },
    {
      "id": "18195958162174905",
      "caption": "Example post 3"
    }
  ]
}

3. `dimensions` removed

The dimensions property has been removed from post objects. Image dimensions can now be accessed in the new sizes property, described below.

[
  {
    "id": "17842915793354225",
    "timestamp": "2020-09-04T22:27:19+0000",
    "permalink": "https://www.instagram.com/p/CEuzou0hKS2/",
    "mediaType": "IMAGE",
    "mediaUrl": "https://scontent-dfw5-1.cdninstagram.com/v/t51.29350...",
    "caption": "Photo credit: Chuttersnap\n\nThe year 1866 was signalised by...",
    "prunedCaption": "Photo credit: Chuttersnap\n\nThe year 1866 was...",
    "hashtags": [...],
    "mentions": [...],
    "colorPalette": {...},
    "dimensions": {
      "height": 1080,
      "width": 1080
    }
  },
  ...
]

{
  "posts": [
    {
      "id": "17842915793354225",
      "timestamp": "2020-09-04T22:27:19+0000",
      "permalink": "https://www.instagram.com/p/CEuzou0hKS2/",
      "mediaType": "IMAGE",
      "mediaUrl": "https://scontent-dfw5-1.cdninstagram.com/v/t51.29350...",
      "caption": "Photo credit: Chuttersnap\n\nThe year 1866 was signalised by...",
      "prunedCaption": "Photo credit: Chuttersnap\n\nThe year 1866 was...",
      "hashtags": [...],
      "mentions": [...],
      "colorPalette": {...},
      "sizes": {
        "small": {
          "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/small.webp",
          "height": 400,
          "width": 400
        },
        "medium": {
          "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/medium.webp",
          "height": 700,
          "width": 700
        },
        "large": {
          "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/large.webp",
          "height": 1000,
          "width": 1000
        },
        "full": {
          "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/full.webp",
          "height": 1280,
          "width": 1280
        }
      },
    },
  ...
  ]
}

New properties

Metadata

Both basic and advanced feeds now have access to a number of metadata fields. Specifically: username, biography, profilePictureUrl, website, followersCount, and followsCount.

{
  "username": "behold.examples",
  "profilePictureUrl": "https://cdn2.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/4315645351781294/profile.webp",
  "website": "https://behold.so",
  "followersCount": 105,
  "followsCount": 3,
  "posts": [...]
}

Sizes

Post objects now have a sizes property. While the mediaUrl and thumbnailUrl properties contain the raw original images direct from Instagram, the images in sizes have been optimized, resized and converted to webp format.

For video posts, the images in sizes contain a thumbnail image. The video itself can still be accessed at mediaUrl.

The images in sizes are resized to fit the following maximum dimensions (both height and width) while maintaining the original aspect ratio:

Small: 400px
Medium: 700px
Large: 1000px
Full: 2000px

"sizes": {
  "small": {
    "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/small.webp",
    "height": 400,
    "width": 400
  },
  "medium": {
    "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/medium.webp",
    "height": 700,
    "width": 700
  },
  "large": {
    "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/large.webp",
    "height": 1000,
    "width": 1000
  },
  "full": {
    "mediaUrl": "https://cdn.behold.pictures/yZDwFyskeEQiF7cA6LW1gxe4RF02/zFgp2Jbbk23Ovf1ZUOhq/17842915793354225/full.webp",
    "height": 1280,
    "width": 1280
  }
}