Querying Data

Learn common patterns for querying Lens data.

The Lens API, utilizing the versatility of GraphQL, enables diverse data querying methods. This page delves into common patterns for querying data through Lens, including:

The Lens API takes snapshots of media content referenced by Profile Metadata and Publication Metadata objects. These snapshots are then served from a Content Delivery Network (CDN) to ensure quick and reliable access.

In the specific it snapshots the following media content:

There are some limits to the size of the media content that can be snapshotted. The Lens API will not snapshot media content that exceeds the following limits:

Image snapshots are delivered through ImageKit, a powerful image optimization and delivery service. ImageKit automatically optimizes the images for web use and serves them from a global CDN.

When querying image data from the Lens API, you can retrieve the original image URI, a CDN-optimized image URL, and additional image URLs that specify certain transformations to adapt the images to your application's requirements.

type ImageSet = {  raw: Image;  optimized: Image | null;  small: Image | null;  medium: Image | null;};
type EncryptableImageSet = {  raw: EncryptableImage;  optimized: Image | null;  small: Image | null;  medium: Image | null;};

type ProfileCoverSet = {  raw: Image;  optimized: Image | null;  transformed: Image | null;};
type ProfilePictureSet = {  raw: Image;  optimized: Image | null;  thumbnail: Image | null;};

const lensConfig: LensConfig = {  // ...
  params: {    image: {      small: {        width: "300px",        height: "200px",        keepAspectRatio: true,      },
      medium: {        width: "640px",        height: "480px",        keepAspectRatio: true,      },    },
    profile: {      thumbnail: {        width: "100px",        height: "100px",        keepAspectRatio: true,      },
      cover: {        width: "100%",        keepAspectRatio: true,      },    },  },};

Audio snapshots are delivered through CloudFront, Amazon CDN service.

When you query audio data, you can retrieve both the original audio URI and an CDN-optimized URL provided by CloudFront.

Specifically, when you retrieve publication audo data, you will encounter EncryptableAudioSet objects. The respective types for each type of integration are detailed below.

type EncryptableAudioSet = {  raw: EncryptableAudio;  optimized: Audio | null;};

These object have the following properties:

The raw original can be used to enable users to download the original audio, which can be especially useful for collected publications.

Video snapshots are delivered through Livepeer, an open-source video streaming network that offers transcoding and delivery services.

When you query video data, you can retrieve both the original video URI and an optimized HLS URL provided by Livepeer.

Specifically, when you retrieve publication video data, you will encounter EncryptableVideoSet objects. The respective types for each type of integration are detailed below.

type EncryptableVideoSet = {  raw: EncryptableVideo;  optimized: Video | null;};

These object have the following properties:

The raw original can be used to enable users to download the original video, which can be especially useful for collected publications.

When working with media snapshots, it's important to understand that the snapshot version of the media content may not always be available. This could be because the data was requested before the snapshotting process finished, or because the media URI was end-to-end encrypted, which prevents the snapshotting process from taking place.

You always want to ensure that you have a fallback strategy in place to handle these scenarios, like the following example.

function getSmallImage(set: ImageSet): string {  return set.small?.uri || set.optimized?.uri || set.raw.uri;}

It's also important to note that media URIs may not be directly usable URLs. They could be IPFS or Arweave URIs, which in many circumstances require resolution into URLs before use.

The following example illustrates a strategy you can use to resolve media URLs under various circumstances.

function resolveUrl(uri: string): string {  try {    const { protocol } = new URL(uri);
    switch (protocol) {      case "ar:":        return `${trustedArweaveGateway}${uri.replace("ar://", "")}`;
      case "ipfs:":        return `${trustedIpfsGateway}${uri.replace("ipfs://", "")}`;
      default:        return uri;    }  } catch {    // in the case of malformed URIs or encrypted URIs fallback to a placeholder    return "/assets/placeholder.jpg";  }}

Where trustedArweaveGateway and trustedIpfsGateway are the URLs of the gateways you want to use to resolve Arweave and IPFS URIs, respectively.

The Lens API provides contextual crypto-to-fiat exchange rates for any cryptocurrency amount, whether it's a fee (collect fee, follow fee) or a reward (collect reward, follow reward, mirror reward). This feature is particularly beneficial for applications aiming to offer a more intuitive user experience by displaying amounts in a familiar fiat currency.

const usdAmount = maticAmount.convert(maticUsdRate);
console.log(usdAmount.toString()); // "42.56 USD"

import { LensConfig, SupportedFiatType } from '@lens-protocol/react-web';
const lensConfig: LensConfig = {  // ...
  params: {    fxRateFor: SupportedFiatType.Gbp,  },};

The Lens API offers a range of statistics that can provide valuable insights into a Profile or a Publication.

Publication statistics include:

Profile statistics include:

By default, any number related to publications (such as post counts and comment counts) encompasses the entire Lens ecosystem. However, you can tailor these statistics to specific apps by specifying the App IDs to be counted.

import { appId, LensConfig } from '@lens-protocol/react-web';
const lensConfig: LensConfig = {  // ...
  params: {    statsFor: [appId('hey'), appId('orb')],  },};