Flask - Dub

1. Prerequisites#

To follow this guide, you will need to:

2. Install and initialize the Dub Python SDK#

Install#

To install the Dub Python SDK, run the following command:

pip

pip install dub

Initialize#

Initialize the Dub Python SDK by creating a new instance of the Dub class.

import osimport dubfrom dub.models import operationsd = dub.Dub(  token=os.environ['DUB_API_KEY'],)

3. Create link#

Let's create a short link using the Dub Python SDK.

app.py

def create_link():  res = d.links.create(request={    "url": "https://google.com",  })  return res.short_link

Full list of available attributes for the Link model

urlstringrequired#

The destination URL of the short link.

domainstring#

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

keystring#

The short link slug. If not provided, a random 7-character slug will be generated.

keyLengthnumber#

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength.

externalIdstring | null#

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with 'ext_' when passed as a query parameter). This key is unique across your workspace.

tenantIdstring | null#

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.

programIdstring | null#

The ID of the program the short link is associated with.

partnerIdstring | null#

The ID of the partner the short link is associated with.

folderIdstring | null#

The unique ID of an existing folder to assign the short link to.

prefixstring#

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversionboolean#

Whether to track conversions for the short link. Defaults to false if not provided.

Default: false

identifierstring | null#

The identifier of the short link that is unique across your workspace. If set, it can be used to identify your short link for client-side click tracking.

archivedboolean#

Whether the short link is archived. Defaults to false if not provided.

Default: false

publicStatsboolean#

Deprecated: Use dashboard instead. Whether the short link's stats are publicly accessible. Defaults to false if not provided.

Default: false

tagIdsstring | string[]#

The unique IDs of the tags assigned to the short link.

tagNamesstring | string[]#

The unique name of the tags assigned to the short link (case insensitive).

commentsstring | null#

The comments for the short link.

expiresAtstring | null#

The date and time when the short link will expire at.

expiredUrlstring | null#

The URL to redirect to when the short link has expired.

passwordstring | null#

The password required to access the destination URL of the short link.

proxyboolean#

Whether the short link uses Custom Link Previews feature. Defaults to false if not provided.

Default: false

titlestring | null#

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

descriptionstring | null#

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

imagestring | null#

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

videostring | null#

The custom link preview video (og:video). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

rewriteboolean#

Whether the short link uses link cloaking. Defaults to false if not provided.

Default: false

iosstring | null#

The iOS destination URL for the short link for iOS device targeting.

androidstring | null#

The Android destination URL for the short link for Android device targeting.

geoobject#

Geographic targeting for the short link. Allows you to redirect users based on their location.

doIndexboolean#

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

Default: false

utm_sourcestring | null#

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

utm_mediumstring | null#

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

utm_campaignstring | null#

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

utm_termstring | null#

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

utm_contentstring | null#

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

refstring | null#

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

webhookIdsstring[] | null#

An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

testVariantsobject[]#

An array of A/B test URLs and the percentage of traffic to send to each URL. Requires 2-4 variants with percentages between 10-90.

testStartedAtstring | null#

The date and time when the tests started.

testCompletedAtstring | null#

The date and time when the tests were or will be completed.

tagIdstring | null#

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link.

Optionally, you can also pass an externalId field which is a unique identifier for the link in your own database to associate it with the link in Dub's system.

app.py

def create_link(request):  res = d.links.create(request={    "url": "https://google.com",    "external_id": "12345",  })  return res.short_link

This will let you easily update the link or retrieve analytics for it later on using the externalId instead of the Dub linkId.

4. Upsert link#

Dub Python SDK provides a method to upsert a link – where an existing link is updated if it exists, or a new link is created if it doesn't. so you don't have to worry about checking if the link already exists.

app.py

def upsert_link(request):  res = d.links.upsert(request={    "url": "https://google.com",  })  return res.short_link

This way, you won't have to worry about checking if the link already exists when you're creating it.

5. Update link#

Let's update an existing link using the Dub Python SDK.

You can do that in two ways:

Using the link's linkId in Dub's system.
Using the link's externalId in your own database (prefixed with ext_).

app.py

# Update a link by its linkIddef update_link(request):  res = d.links.update(link_id="clx1gvi9o0005hf5momm6f7hj", request_body={    "url": "https://google.uk",  })  return res.short_link# Update a link by its externalIddef update_link(request):  res = d.links.update(external_id="ext_12345", request_body={    "url": "https://google.uk",  })  return res.short_link

6. Retrieve analytics for link#

Dub allows you to retrieve analytics for a link using the Dub Python SDK.

app.py

# Retrieve the timeseries analytics for the last 7 days for a linkdef analytics(request):  res = d.analytics.retrieve(request={    "link_id": "clx1gvi9o0005hf5momm6f7hj",    "interval": "7d",    "group_by": "timeseries",  })  return str(res)

Similarly, you can retrieve analytics for a link using the externalId field.

views.py

# Retrieve the timeseries analytics for the last 7 days for a linkdef analytics(request):  res = d.analytics.retrieve(request={    "external_id": "ext_12345",    "interval": "7d",    "group_by": "timeseries",  })  return str(res)

7. Examples#

Python Example

See the full example on GitHub.