Goo.su API

Welcome to the Goo.su API, your comprehensive tool for managing, tracking, and optimizing your shortened URLs. Designed to streamline your link management tasks, our API offers a wide range of features tailored to meet your needs.

1. Link Shortening

Easily shorten long URLs into more manageable, shorter links suitable for sharing and tracking.

2. Link Management

Manage your shortened links effortlessly, with options to edit, update, or delete them as needed.

3. Link Statistics

Gain valuable insights into your link performance with detailed click statistics and analytics.

4. Link Groups Management

Organize your links efficiently by creating and managing link groups for better categorization and tracking.

5. Custom Domains

Brand your links with custom domains to reinforce your brand identity and increase trust among your audience.

6. Tracking Pixels

Utilize tracking pixels to monitor user interactions and gather data for targeted marketing campaigns.

...and much more!

Base URL

All API requests must be made to the following base URL:

https://goo.su/api

Requests

You need to use in HTTP requests only HTTPS protocol and UTF-8 encoding.
All requests require a header X-Goo-Api-Token.

Responses

All responses are returned in JSON format and UTF-8 encoding.

Possible response HTTP status codes:

200 OK. The request was processed successfully.
400 Bad Request. The request contains invalid parameters.
401 Unauthorized. Token is required for this request.
403 Forbidden. Not enough token rights for this request. The client's request was understood by the server, but access to the requested resource is forbidden due to the user's current tariff plan not providing access to the service. This error is specifically tailored to users who have not subscribed to or have an expired subscription for the service
405 Method Not Allowed. status code indicates that the method received in the request-line is known by the origin server but not
supported by the target resource.
404 Not Found. Unknown API Method.
500 Internal Server Error. The error is related to technical problems on the server.

Additional information on the request, error description or recommendations can be found in the message field.

Links

Create short link

POST /links/create

Service allows to create short link with any parameters

Required parameters:

url String URL to be shortened

Optional parameters:

title String|null Link title.
alias String|null This value will be displayed as an identifier. For example for "cool" alias, the short link will look like this - https://goo.su/cool. Max length 10 characters. By default, the alias will be randomly generated.
is_public Boolean By choosing the PUBLIC type, the link may be available to other Internet users. If you want the link to be private, set the value to Personal. By default value is TRUE
password String|null Set a password to protect your links from unauthorized access. By default this value is NULL.
group_id Integer|null The id of one of your groups. By setting the identifier, the created link will be available among other links within the group. By default this value is NULL. Please note: This functionality is available in some tariff plans.
active_before Date|null Format 'Y-m-d'. The date until which the link will be available. After the expiration of the period, referrals to the link will be unavailable. If this parameter is not set, then the link will always be available. By default this value is NULL.
custom_domain_id Integer|null Custom domain ID. Used to brand your link. For example, for a custom domain 'brand.com' the link will look like https://brand.com/cool. Use your custom domain ID. You can get a list of your domains in the custom domains section. Please note: This functionality is available in some tariff plans. By default this value is NULL.
tracking_pixels_ids Array of Integer|null List of your tracking pixel IDs. Optimize user engagement using tracking pixels. Attach one or multiple pixels to track and analyze user activity clicking your shortened links. You can get a list of your tracking pixels in the tracking pixels section. Use id of your tracking pixels, for example [199, 3459, 9999]. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_title String|null The title metadata. Using as tag <title>...</title> when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_description String|null The description metadata. Using as tag when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_keywords String|null Keywords metadata. Using as tag when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_og:title String|null The Og:title metadata. Using as tag when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_og:description String|null The Og:description metadata. Using as tag when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
meta_og:image String|null The Og:image metadata. Using as tag when redirecting. Please note: This functionality is available in some tariff plans. By default this value is NULL.
tags Array of String|null Add tags to your links to make it easier to organize and find quickly. Please note: This functionality is available in some tariff plans. By default this value is NULL.

Request example:

curl --request POST \--url https://goo.su/api/links/create \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXXX' \--data '
{
    "url":"https://www.api.com",
    "alias":"cool",  
    "is_public": true,  
    "group_id":2,
    "tags": ["job"]  
}'

Response example:

{  
    "successful": true,  
    "message": "Link successfully created",  
    "link": {  
        "long_url": "https://www.api.com",  
        "short": "cool",  
        "hits": 0,  
        "group": {  
            "id": 2,  
            "name": "Test Group",  
            "short": "wow",  
            "description": "Description of the group",  
            "url": "https://goo.su/g/wow"  
        },
        "tags": ["job"]
    },  
    "short_url": "https://goo.su/cool",  
    "qr": {  
      "base64": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QAAd2KE6QAAAGPSURBVGje7ZpdroQgDIV5Y9m4ZHbQ64iUU/7u43TIIcag8+nE1LanxRB0RLnHvb+nqU4mg9hPYe+mh8NN3vs8m+R21fsTMTeYMSjaNFqgu7bOiXnG0D0TseOwnZ/mz03Knphz7GPxHFY2bc5eMEjQ84BP7FsYaiSc/CuluvxLzCc2FcDPEBwZYng054l5wMbKJYFr69ZhqQTzEs+J+cbUrCOWalJuyVexOiHmBHt9E3UR2vdhmqdrRs7EXGO91h0x24kq+qo5clVcxLxgM6WUsjk0TSfQUULMHzZvNYzaWKtUeCX69yQT84Whb2JAbidrtdvqX8zIp2DXEU/6GtE2jlaYpuYErwf+BTEXWJdJMcOCodXuqr7ENhILQMwVtlx+tR0M49GqvoSYF2xUQTulFALWubt+IzFP2NymNjuLzKukA7DriCc1a22y7fDHxTcw4/rdz2LXcU+6D7lGMolZyyPmF9OSZ4Nh5avrO6t0TMwHNmkPxl5uaZRO2awCEPs+NkTjDpuvsIfWmBJivrA/OACaB5gWD2cAAAAASUVORK5CYII="  
    }  
}

Response fields:

successful Boolean Successful request
message String Text message. By default is NULL
link.long_url String Source url
link.short String Alias of the short link
link.title String|null Title of the link
link.hits Integer Number of clicks on the link
link.tags Array of Strings|null List of link tags
link.group Object|null Group the link belongs to
link.group.id Integer Id of the link group
link.group.name String Name of the link group
link.group.description String Description of the link group
link.group.url String Url of the link group
short_url String Short link
qr.base64 String Image of the QR code of the link in base64 format

List of links

GET /links

Goo.su Api allows to get list of your links.

Optional parameters:

limit Integer The number of links contained in the result. Max value is 25. By default is 25.
offset Integer The number of items to skip. By default is 0.
group_id Integer Id of one of your groups. The result will include links for this group. By default NULL.

Request example:

curl --header 'X-Goo-Api-Token: XXXXXXX' 'https://goo.su/api/links?limit=2&offset=3&group_id=2'

Response example:

{  
    "successful": true,  
    "message": "",  
    "count": 6,  
    "limit": 2,  
    "offset": 3,  
    "links": [  
    {  
        "long_url": "https://docs.google.com/",  
        "short": "A",  
        "title": "Google doc link",  
        "hits": 0,  
        "group": {  
            "id": 2,  
            "name": "Test Group",  
            "short": "wow",  
            "description": "Description of the group",  
            "url": "https://goo.su/g/wow"  
        },  
        "short_url": "https://goo.local/A",  
        "qr": {  
          "base64": "1TcdDYAfMJNqAAvxewusLbDh+eIg1OXqjeFtvb00cj5APCyGNHrBqVp7+xfCz6RQ65cyevtaKqzVMErWArWF9N0CDgAXOznjb22eh+xl38dHJ53tnhbcmLZX3vEvflXe62YxtW+TZ7ftVXsVD4UALrcFGwA7ttu786rAIBmckqMLgKAw4OZi6blE1tyadXIuzEuBQDGnTRkDwHee5DzEu0eAQAfkOlQ8QoA4EHKzNYwiXVpYxlDaKPQze7IPubIuYbCUNZbA6P4FIY9BYYsnCc9WcmK2A+AN4PMEBsbfMCVT8/890/wQcvtzWzzD1chFDtDsaIiFJfqLFXwCpaCNWBMh52xZfCe5Twzwh57GZGSPnwDZE+zOSjvzujc6Rk0QAcO5OZesoE1JjZWy3lXe9pv/kJbepEa104O4aKxqzt15C0hCfPFLk2ShDzqsk4WT60ne+5l3xixy7l9a5TmzyOw4osovB0AzPwIOoUGzXI2wR3R84l8u0J1lip4BUvBUrC+APT/l5ygYhinPbUAAAAASUVORK5CYII="  
        },  
      "active_before":"2020-12-15",  
      "tracking_pixels": [  
            {  
                "id": 684,  
                "name": "my Google pixel #1",  
                "code": "UA-141664405-2",  
                "type": "Google Analytics",  
                "type_id": 2  
            },  
            {  
                "id": 686,  
                "name": "my yandex metrika pixel",  
                "code": "54142170",  
                "type": "Yandex.Metrika",  
                "type_id": 1  
            },  
            {  
                "id": 687,  
                "name": "facebook pixel#5",  
                "code": "168345577755674",  
                "type": "Facebook Pixel",  
                "type_id": 3  
            }  
        ],  
        "meta": {  
            "title": "Sales report 2018",  
            "description": "A detailed report including data from all departments of the company for 2018",  
            "keywords": "sales, 2018, reports",  
            "og:title": "Report 2018",  
            "og:description": null,  
            "og:image": "https://facebook.com/sdE/1.jpg"  
        }  
    },  
        {  
            "long_url": "http://test.ru",  
            "short": "p",  
            "title": null,  
            "hits": 0,  
            "group": {  
                "id": 2,  
                "name": "Test Group",  
                "short": "wow",  
                "description": "Description of the group",  
                "url": "https://goo.su/g/wow"  
            },  
            "short_url": "https://goo.local/p",  
            "qr": {  
              "base64": "1rc1av1mtOveAmEWABxawgAUsBCxgAQtYwFpR1WxuuHieo/JZlKquPv5qh9Ud25/bDQLrbzVFrOxOP0pVMY73+3ZY272afQfiNg+1Zo6crHfNKx3ELAI8sIAFLGAhYAELWMAC1orq2tyw9ESnFXiU+ktYt5t2WLul99XLjiLypf4eJjvKDZnZ9FgbsrjMoz2s4MfTcrJKyXyp3gkcNTuK1DQ7s+pcbTgmJysBHljAAhawELCABSxgAQtYSNG/sv+mdR376s4AAAAASUVORK5CYII="  
            },  
            "active_before": null,  
            "tracking_pixels": [],  
            "meta": {  
                "title": null,  
                "description": null,  
                "keywords": null,  
                "og:title": null,  
                "og:description": null,  
                "og:image": null  
            }  
        }  
    ]  
}

Response fields:

successful Boolean Successful request
message String Text message. By default is NULL
count Integer Total number of links on request
limit Integer The number of links contained in the result.
offset Integer The number of items to skip.
links Array of Link List of links.
links[].long_url String Source url
links[].short String Alias of the short link
links[].hits Integer Number of clicks on the link
links[].title String|null Title of the link
link.group Object|null Group the link belongs to
links[].group.id Integer Id of the link group
links[].group.name String Name of the link group
links[].group.description String Description of the link group
links[].group.url String Url of the link group
links[].tracking_pixels Array of objects Link tracking pixels used
links[].tracking_pixels[].id Integer Tracking Pixel ID
links[].tracking_pixels[].name String Tracking Pixel name
links[].tracking_pixels[].code String Tracking Pixel code
links[].tracking_pixels[].type String Tracking Pixel type
links[].tracking_pixels[].type_id Integer Tracking Pixel type id
links[].meta Object Metadata of the link. Display in meta tags on the redirect page if one of these options is set.
links[].meta.title Sting|null The title metadata. Using as tag <title>...</title> when redirecting
links[].meta.description Sting|null The description metadata. Using as tag <meta name="description" content="..."> when redirecting
links[].meta.keywords Sting|null Keywords metadata. Using as tag <meta name="keywords" content="..."> when redirecting
links[].meta.og:title Sting|null The Og:title metadata. Using as tag <meta property="og:title" content="..." /> when redirecting
links[].meta.og:description Sting|null The Og:description metadata. Using as tag <meta property="og:description" content="..." /> when redirecting
links[].meta.og:image Sting|null The Og:image metadata. Using as tag <meta property="og:image" content="..." /> when redirecting
links[].short_url String Short link
links[].qr.base64 String Image of the QR code of the link in base64 format
links[].active_before Date|null The date until which the link will be available. After the expiration of the period, referrals to the link will be unavailable. If this parameter is not set, then the link will always be available.

Delete short link

POST|DELETE /links/delete/<alias>

You can remove your short link using the link alias.

Request example:

curl --request POST \--url https://goo.local/api/links/delete/cool \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXXX'

Response example:

{  
    "successful": true,  
    "message": "Link removed"  
}

Groups

Create group

POST /groups/create

Service allows to create groups for your links.

Required parameters:

name String Group name

Optional parameters:

description String Group description. Default NULL
alias String This value will be displayed as an identifier. For example for "super" alias, link to new group will look like this - https://goo.su/g/super. Max length 10 characters. By default, the alias will be randomly generated.
is_active Boolean Whether this link group is publicly viewable. By default value is TRUE
is_rotation Boolean If set, the above URL will redirect to a random link from the group instead of displaying all links belonging to the group. By default value is FALSE

Request example:

curl --request POST \--url https://goo.su/api/groups/create \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXXX' \--data '
{
    "name":"My links",
    "description":"Links to my social networks",  
    "alias": "super",  
    "is_active":true,  
    "is_rotation":true  
}'

Response example:

{  
    "successful": true,  
    "message": "Group created",  
    "group": {  
        "id": 3,  
        "name": "My links",  
        "short": "super",  
        "description": "Links to my social networks",  
        "url": "https://goo.local/g/super"  
    }  
}

Response fields:

successful Boolean Successful request
message String Text message.
group.id Integer Group ID
group.name String Group name
group.short String Group alias
group.description String Group description
group.url String Group url

List of groups

GET /groups

You can receive list of your groups.

Optional parameters:

limit Integer The number of groups contained in the result. Max value is 100. By default is 100.
offset Integer The number of items to skip. By default is 0.

Request example:

curl --request GET \--url https://goo.su/api/groups \--header 'token: XXXXX'

Response example:

{  
    "successful": true,  
    "message": "",  
    "count": 1,  
    "groups": [  
        {  
        "id": 3,  
        "name": "My links",  
        "short": "super",  
        "description": "Links to my social networks",  
        "url": "https://goo.local/g/super"  
        }  
    ]  
}

Response fields:

successful Boolean Successful request
message String Text message.
groups Array of Group List of your groups.
group.id String Group id
group.name String Group name
group.short String Group alias
group.description String Group description
group.url String Group url

Delete group

POST|DELETE /groups/delete/<group_id>

You can remove your group using the group id.

Request example:

curl --request POST \--url https://goo.su/api/groups/delete/3 \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXX'

Response example:

{  
    "successful": true,  
    "message": "Group removed"  
}

Tracking Pixels

Create a tracking pixel

POST /tracking-pixels/create

The Goo.su service allows you to create tracking pixels for your links. This allows you to track and analyze the behavior of users who follow your shortened links.
NOTE: Available on select plans. See https://goo.su/plans

Required parameters:

name String The tracking pixel name.
code String Tracking pixel code. You can get the pixel code from the corresponding service,
for example Google Analytics or Yandex.Metrika

type_id Integer ID of the tracking pixel service. Available values:

Yandex.Metrika: 1  
Google Analytics: 2  
Facebook Pixel: 3  
LinkedIn Insight: 4  
Twitter Pixel: 5  
Hotjar: 6  
DoubleClick Floodlight: 7  
Pinterest: 8  
Mailchimp: 9

Request example:

curl --request POST \--url https://goo.su/api/tracking-pixels/create \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXXX' \--data '{"name":"Facebook pixel #1","code": "18623354455",  
"type_id": 3  
}'

Response example:

{  
    "successful": true,  
    "message": "The tracking pixel has been created.",  
    "tracking_pixel": {  
        "id": 2690,  
        "name": "Facebook pixel #1",  
        "code": "18623354455",  
        "type": "Facebook Pixel",  
        "type_id": 3  
    }  
}

Response fields:

successful Boolean Successful request
message String Text message.
tracking_pixel Object Created tracking pixel data
tracking_pixel.id Integer ID of the created tracking pixel
tracking_pixel.name String Name of the created tracking pixel
tracking_pixel.code String Code of the created tracking pixel
tracking_pixel.type String Type of the created tracking pixel
tracking_pixel.type_id Integer ID of the type of created tracking pixel

List of tracking pixels

GET /tracking-pixels

Returns a list of your tracking pixels. NOTE: Available on select plans. See https://goo.su/plans

Optional parameters:

limit Integer The number of tracking pixels contained in the result. Max value is 100. By default is 100.
offset Integer The number of items to skip. By default is 0.

Request example:

curl --request GET \--url https://goo.su/api/tracking-pixels \--header 'x-goo-api-token: XXXXX'

Response example:

{  
    "successful": true,  
    "message": "",  
    "count": 7,  
    "tracking_pixels": [  
        {  
            "id": 2690,  
            "name": "Facebook pixel #1",  
            "code": "18623354455",  
            "type": "Facebook Pixel",  
            "type_id": 3  
        },  
        {  
            "id": 2649,  
            "name": "PINTEREST pixel",  
            "code": "4556",  
            "type": "Pinterest",  
            "type_id": 8  
        },  
        {  
            "id": 2388,  
            "name": "LinkedIn pixel",  
            "code": "9999333444555",  
            "type": "LinkedIn Insight",  
            "type_id": 4  
        }  
    ]  
}

Response fields:

successful Boolean Successful request
tracking_pixels Array of objects List of your tracking pixels
tracking_pixels[].id Integer ID of the tracking pixel
tracking_pixels[].name String Tracking pixel name
tracking_pixels[].code String Tracking pixel code
tracking_pixels[].type String Tracking pixel type
tracking_pixels[].type_id String Tracking pixel type id

Delete tracking pixel

POST|DELETE /tracking-pixels/delete/<tracking_pixel_id>

You can remove your tracking pixel using id.

Request example:

curl --request POST \--url https://goo.su/api/tracking-pixels/delete/685 \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXX'

Response example:

{  
    "successful": true,  
    "message": "Tracking pixel removed"  
}

Custom domains

The Goo.su service allows to create your custom domains. When a link includes your brand, it helps people recognize and associate your links with your product or company. When they see your brand, they trust your links. This leads to a higher click-through rate.

You can read more about custom domains here.

Create a cutom domain

POST /custom-domain/create

NOTE: Available on select plans. See https://goo.su/plans

Required parameters:

domain String Custom domain name. For example, brand.com. Your short link will look like https://brand.com/link with this domain.

Request example:

curl --request POST \--url https://goo.su/api/custom-domain/create \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXXX' \--data '{  
"domain":"brand.com"  
}'

Response example:

{  
    "successful": true,  
    "message": "The custom domain has been created.",  
    "custom_domain": {  
        "id": 2340,  
        "domain": "brand.com",  
        "status": {  
            "id": 0,  
            "name": "In Verification"  
        }  
    },
    "custom_domains_remaining_in_the_current_month": 4
}

Response fields:

successful Boolean Successful request
message String Text message.
custom_domain Object Created custom domain data
custom_domain.id Integer ID of the created custom domain
custom_domain.domain String Domain name
custom_domain.status Object Current verification status
custom_domain.status.id Integer ID of verification status
custom_domain.status.id.name Integer Verification status
custom_domains_remaining_in_the_current_month Integer Number of custom domains you can create this month, according to your pricing plan

List of custom domains

GET /custom-domains

Returns a list of your custom domains. NOTE: Available on select plans. See https://goo.su/plans

Optional parameters:

limit Integer The number of tracking pixels contained in the result. Max value is 100. By default is 100.
offset Integer The number of items to skip. By default is 0.

Request example:

curl --request GET \--url https://goo.su/api/custom-domains \--header 'x-goo-api-token: XXXXX'

Response example:

{  
    "successful": true,  
    "succes": true,  
    "message": "",  
    "count": 3,  
    "custom_domains": [  
        {  
            "id": 2340,  
            "domain": "brand.com",  
            "status": {  
                "id": 1,  
                "name": "Verified"  
            }  
        },  
        {  
            "id": 2329,  
            "domain": "test-domain.com",  
            "status": {  
                "id": 1,  
                "name": "Verified"  
            }  
        },  
        {  
            "id": 2123,  
            "domain": "goo.dev",  
            "status": {  
                "id": 0,  
                "name": "In Verification"  
            }  
        }  
    ]  
}

Response fields:

successful Boolean Successful request
custom_domains Array of Objects List of your custom domains
custom_domains[].id Integer ID of the custom domain
custom_domains[].domain String Domain name
custom_domains[].status Object Current verification status
custom_domains[].status.id Integer ID of verification status
custom_domains[].status.id.name Integer Verification status

Delete custom domain

POST|DELETE /custom-domains/delete/<custom_domain_id>

You can remove your custom domain using id.

Request example:

curl --request POST \--url https://goo.su/api/custom-domains/delete/2329 \--header 'content-type: application/json' \--header 'x-goo-api-token: XXXXX'

Response example:

{  
    "successful": true,  
    "message": "Custom domain removed"  
}