Goo.su API

  1. General information

1.1. URL

1.2. Requests

1.3. Responses

  1. Links

2.1 Create short link

2.2 List of links

2.3 Delete short link

  1. Groups

3.1 Create group

3.2 List of groups

3.3 Delete group

  1. Tracking pixels

4.1 Create tracking pixel

4.2 List of tracking pixels

4.3 Delete tracking pixel

  1. Custom domains

5.1 Create custom domain

5.2 List of custom domains

5.3 Delete custom domain

General information

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:

  1. 200 OK. The request was processed successfully.
  2. 400 Bad Request. The request contains invalid parameters.
  3. 401 Unauthorized. Token is required for this request.
  4. 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
  5. 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.
  6. 404 Not Found. Unknown API Method.
  7. 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.

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  
}'  

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"  
        }  
    },  
    "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.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"  
        }  
    }  
}  

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

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"  
}  
arrow-up icon