links

Link shortener and analytics endpoint

Links Overview

With the links endpoint your can shorten links to include in social posts.

Max Pack Required

The Ayrshare link shortener offers several valuable benefits social publishing.

• Condense long and complex URLs for more visually appealing, concise, and memorable.

• Analytics and tracking capabilities, allowing you to monitor link performance, engagement, and audience insights.

• Save valuable character space, especially on platforms like Twitter where character limits are stringent.

• Add a custom link domain with your own url.

Create a short link from a URL

POST https://app.ayrshare.com/api/links

Provide a URL and a shortened link will be returned. Analytics can then be gathered on the clicks, browser type, etc.

Submitting the same URL for shortening will always result in the same shortened link. To generate a unique shortened link for the same URL, you can add extra query parameters to it. For example, appending a unique identifier like https://ayrshare.com?uniqueId=123 will create a distinct shortened link.

You may also include UTM parameters, which will be embedded in the shortened URL link.

Max Pack Required

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.

Request Body

Name	Type	Description
url*	string	URL to be shortened. Must be a valid URL starting with https://
utmId	string	Used to identify which Google Analytics ads campaign this referral references. Use utm_id to identify a specific ads campaign.
utmSource	string	Used to identify a search engine, newsletter name, or other source.
utmMedium	string	Used to identify a medium such as email or cost-per-click.
utmCampaign	string	Used for keyword analysis. Used to identify a specific product promotion or strategic campaign.
utmTerm	string	Used for paid search. Used to note the keywords for this ad.
utmContent	string	Used for A/B testing and content-targeted ads. Used to differentiate ads or links that point to the same URL.

200: OK Successful shortened link

{
    "created": "2023-07-17T15:20:51.118Z",
    "id": "yC0fTl",
    "originalUrl": "https://www.ayrshare.com/?utm_source=looking",
    "shortUrl": "https://ayrs.io/yC0fTl",
    "status": "success",
    "utmSource": "looking"
}

400: Bad Request Error shortening link

{
    "action": "request",
    "status": "error",
    "code": 126,
    "message": "Shorten URL failed. Please verify the URL is properly formatted and the correct UTM parameters are used."
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_KEY" \
-H 'Content-Type: application/json' \
-d '{"url": "https://www.ayrshare.com", "utmSource": "google_ads"}' \
-X POST https://app.ayrshare.com/api/links

Node.js

const API_KEY = "API_KEY";

fetch("https://app.ayrshare.com/api/links", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      },
      body: JSON.stringify({
        url: "https://www.ayrshare.com", // required
        utmSource: ""google_ads", // optional
      }),
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

payload = {'url': 'https://www.ayrshare.com', 
        'utmSource': 'google_ads"}
headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.post('https://app.ayrshare.com/api/links', 
    json=payload, 
    headers=headers)
    
print(r.json())

PHP

<?php
require 'vendor/autoload.php';// Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html

$client = new GuzzleHttp\Client();
$res = $client->request(
    'POST',
    'https://app.ayrshare.com/api/links',
    [
        'headers' => [
            'Content-Type'  => 'application/json',
            'Authorization' => 'Bearer API_KEY'
        ],
        'json' => [
            'url' => 'https://www.ayrshare.com',
            'utmSource' => 'google_ads', // optional
        ]
    ]
);

echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT);

Go

package main

import (
	"bytes"
	"encoding/json"
	"log"
	"net/http"
)

func main() {
	message := map[string]interface{}{
		"url":      "https://www.ayrshare.com",
		"utmSource": "goggle_ads",
	}

	bytesRepresentation, err := json.Marshal(message)
	if err != nil {
		log.Fatalln(err)
	}

	req, _ := http.NewRequest("POST", "https://app.ayrshare.com/api/links",
		bytes.NewBuffer(bytesRepresentation))

	req.Header.Add("Content-Type", "application/json; charset=UTF-8")
	req.Header.Add("Authorization", "Bearer API_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal("Error:", err)
	}

	res.Body.Close()
}

C#

using System;
using System.Net;
using System.IO;

namespace PostAnalyticsPOSTRequest_charp
{
    class PostAnalytics
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/analytics/links";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Method = "POST";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                string json = "{\"url\" : \"https://www.ayrshare.com\","
                    + "\"utmSource\" :\"google_ads\"";

                streamWriter.Write(json);
                streamWriter.Flush();
            }

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

---

Get analytics on shortened links

GET https://app.ayrshare.com/api/links/:id

Return analytics for all shortened links or a single link for a given link ID. For example:

⮕ https://app.ayrshare.com/api/links/yC0fTl returns analytics for ID yC0fTl

⮕ https://app.ayrshare.com/api/links returns all link analytics.

Max Pack Required

Path Parameters

Name	Type	Description
id	string	Provide the shortened link ID returned from the POST /links request as a path parameter. For example: https://app.ayrshare.com/api/links/yC0fTl If no link ID is provided, all links are returned.

Query Parameters

Name	Type	Description
fromCreatedDate	string	Get history of links shortened after this date. Accepts a UTC date time. For example, use format "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z".
toCreatedDate	string	Get history of links shortened before this date. Accepts a UTC date time. For example, use format "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z".
fromClickDate	string	Get history of links clicked after this date. Accepts a UTC date time. For example, use format "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z".
toClickDate	string	Get history links clicked after this date. Accepts a UTC date time. For example, use format "YYYY-MM-DDThh:mm:ssZ" and send as "2023-07-08T12:30:00Z".

Headers

Name	Type	Description
Authorization*	string	Format: Authorization: Bearer API_KEY. See Overview for more information.

200: OK Successful analytics on a single link

{
    "status": "success",
    "analytics": {
        "browserCounts": {
            "chrome": 15
        },
        "created": "2023-06-29T00:57:12.220Z",
        "id": "yC0fTl",
        "originalUrl": "https://www.ayrshare.com/?utm_source=google_ads",
        "refererCounts": {},
        "shortUrl": "https://ayrs.io/yC0fTl",
        "socialClicks": {},
        "status": "success",
        "totalClicks": 15,
        "utmSource": "google_ads"
    }
}

400: Bad Request Error getting link analytics

{
    "status": "error",
    "message": "Unable to find link ID: yC0fTl",
    "code": 187
}

200: OK Successful analytics on all links

{
    "status": "success",
    "analytics": [
        {
            "browserCounts": {
                "chrome": 3
            },
            "created": "2023-04-07T22:33:41.126Z",
            "id": "pHXlbv9JlRxrXj6rstdMu",
            "originalUrl": "https://www.ayrshare.com/",
            "refererCounts": {},
            "shortUrl": "https://ayrs.io/pHXlbv9JlRxrXj6rstdMu",
            "socialClicks": {},
            "totalClicks": 3
        },
        {
            "browserCounts": {
                "edge": 13
            },
            "created": "2023-07-17T15:20:51.118Z",
            "id": "yC0fTl",
            "originalUrl": "https://www.ayrshare.com/?utm_source=looking",
            "refererCounts": {},
            "shortUrl": "https://ayrs.io/yC0fTl",
            "socialClicks": {},
            "totalClicks": 13,
            "utmSource": "looking"
        }
    ]
}

Request Examples

cURL

curl \
-H "Authorization: Bearer API_Key" \
-H 'Content-Type: application/json' \
-X GET https://app.ayrshare.com/api/links/yC0fTl

Node.js

const API_KEY = "API_KEY";

fetch(`https://app.ayrshare.com/api/links/yC0fTl`, {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${API_KEY}`
      }
    })
      .then((res) => res.json())
      .then((json) => console.log(json))
      .catch(console.error);

Python

import requests

headers = {'Content-Type': 'application/json', 
        'Authorization': 'Bearer API_KEY'}

r = requests.delete('https://app.ayrshare.com/api/links/yC0fTl', 
    headers=headers)
    
print(r.json())

PHP

<?php
require 'vendor/autoload.php';    // Composer auto-loader using Guzzle. See https://docs.guzzlephp.org/en/stable/overview.html

$lastdays = "2";
$client = new GuzzleHttp\Client();
$res = $client->request(
    'GET',
    'https://app.ayrshare.com/api/links/yC0fTl',
    [
        'headers' => [
            'Content-Type'      => 'application/json',
            'Authorization'     => 'Bearer API_KEY'
        ]
    ]
);

echo json_encode(json_decode($res->getBody()), JSON_PRETTY_PRINT); 

C#

using System;
using System.Net;
using System.IO;

namespace LinksGETRequest_charp
{
    class Links
    {
        static void Main(string[] args)
        {
            string API_KEY = "API_KEY";
            string url = "https://app.ayrshare.com/api/links/yC0fTl";

            var httpWebRequest = WebRequest.CreateHttp(url);
            httpWebRequest.ContentType = "application/json";
            httpWebRequest.Headers.Add("Authorization", "Bearer " + API_KEY);

            var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
            using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
            {
                var response = streamReader.ReadToEnd();
                Console.WriteLine(response);
            }
        }
    }
}

Custom Link Domain

A custom link domain allows you to personalize and brand the domain name used for link shortening and redirection. Instead of using a generic link shortener domain (e.g., bit.ly, ayr.app), a custom link domain allows you to use own domain name to create shortened links.

Max Pack and Business Plan required.

Please contact us to set up your custom domain.