Support for

Templates : notre API "TCAPI"

Fabrice
by Fabrice 6 years ago
 

Récupère un template, ou récupère les filtres pour cette demande.

Demander un template via son ID

Syntax
/templates/<template_id>/

Récupérer un template.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/12345/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json

Demander une liste de templates

Syntax
/templates/

Récupérer tous les templates disponibles en utilisant plusieurs filtres d'options.

  • If more than one template is returned, then the response is a templates object containing many template items.

  • You can include your own templates using include_my_templates=true or only_my_templates=true and refine that list using workgroup, category and customer filters.

Getting available criteria for filters

If filter_options=0, the response contains templates that match the specified criteria. 

If filter_options=1, the response contains the allowed values of filter criteria, i.e. valid tags or other parameter values (see below).

Where filter criteria are not specified, those aspects are disregarded in the search.

Parameter Description
user_key Your application’s key, from developer.templatecloud.com 
format json or xml
Search Criteria
template_id One template ID. Optional; omit to show all available templates.
include_my_templates

When true, 'private' templates assigned to your workgroup, category, or customer, are added to the public templates. If you specify more than one parameter (of workgroupcategorycustomer),  results are merged.

Default: false.

Adding workgroup=TEMP&category=AAC&customer=TCINST filters only the private templates. Filters are optional.

only_my_templates

When true, only 'private' templates assigned to your workgroup, category, or customer, are returned.  If you specify more than one parameter (of workgroupcategorycustomer),  results are merged.

Default: false.

Optional filters: workgroup=TEMP&category=AAC​&customer=TCINST​.

keywords Matches to tag.name. Optional.
keywords Matches to tag.name. Optional.
collection_id

Matches to a collection. Optional.

Equivalent to searching for a tag of tag type 7 ('collections').

tag_groups tag group IDs (optional). Multiple items allowed, comma-separated.
pages

If required, a value to match template.colour.pages (the number of ‘sides’ or ‘PDF pages’ in a document).

Typical values: 1 or 2.

sizes If specified, return only templates having matching template.size.code or template.size.id. Multiple items allowed, comma-separated.
colour If specified, return only templates having colour tag of matching colour, i.e. colour = template.tag.colour (hexadecimal colour). Specify the colour as 3-byte hexadecimal, RGB ordering, e.g. 0568b4.
designer_id If specified, return only templates designed by this designer.
exclusive_tag_types

0 or 1.

Default value 0: will only list template results that have a match on ALL tag groups you’ve search for.

Override value 1: will list ANY template result that matches at least one of the tag groups you’ve searched for.

Paging and ordering of template results
limit

For a paged response, specify this as the number of results to return per page. Optional.

Allowed range: 1-100.
Default values: &limit=20&page=0.
Typical value: 12.

page

Set the page index of results to return, starting with page = 0. Optional;

Default values: &limit=20&page=0.

sort_key

Allowed values: rank, price, or date.

Default: rank.

sort_order

Allowed values: desc or asc.

Defaults:
asc for sort_key = rank;
desc for sort_key = price|date.

Inclusion of metadata
include

Additional element metadata items to include in each template object. Multiple items allowed, comma-separated. See below.

All options: tags,size,colour,tag_group,images

filter_options 0 or 1. When 1, the response inludes filters rather than templates. See filteroptions=0, below.

Extra response items for include arguments

When (comma-separated) arguments are supplied for the include parameter, extra items are included in the response for each template item. Below is an example of each extra item.

include=size

HTTP response (JSON)
"size": {
    "code": "BC",
    "name": "Business Card",
    "width": "85.0000",
    "height": "55.0000",
    "bleed": "1.5000",
    "units": "mm"
}

include=colour

HTTP response (JSON)
"colour": {
    "coloursfront": 4,
    "coloursreverse": 4,
    "pages": 2
}

include=tags

HTTP response (JSON)
"tags": [
    {
        "id": "214",
        "name": "Business Cards",
        "sales": "16491",
        "taggroup_id": "60",
        "tagtype_id": "3"
    },
    /* more tags */
    ...
]

include=tag_group

HTTP response (JSON)
"tags": [
    {
        ...
        "tag_group": {
            "id": "60",
            "name": "Business Cards",
            "tagtype_id": "3"
        }
    },
    /* more tags */
    ...
]

include=images

HTTP response (JSON)
"images": [
    {
        "0": "http://www.templatecloud.com/api/...",
        "1": "http://www.templatecloud.com/api/...",
        "_attrs": {
            "name": "small"
            "size_code": "S"
        }
    },
    /* more images */
    ...
]

filter_options

filter_options=0

The request returns the matching templates.

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json&include=tags%2Csize%2Ccolour%2Ctags%2Ctag_group%2Cimages&filter_options=0
&tag_groups=2
HTTP response (JSON)
{
 "templates": {
    "0": {
     "id": "5924",
     "name": "Crunchy Cabbages Business Card ",
     "views": "102",
     "date_added": "2011-10-04 15:48:18",
     "designrank": "110",
     "allow_fotolia_library": true, 
     "allow_object_deletion": true, 
     "designed_by": "Norma Liza",
     "designer_id": "693971",
     "price": "20.00",
     "cost_price": "19.00",
     "click_charge": "0.00",
     "price_currency": "USD",
     "tags": [
         /* tag items */
     ],
    "size": {
        "code": "BC",
        "name": "Business Card",
        "width": "85.0000",
        "height": "55.0000",
        "bleed": "1.5000",
        "units": "mm"
     },
     "images": [
         /* image items */
     ],
     "colour": {
        "coloursfront": 4,
        "coloursreverse": 4,
        "pages": 2
     }
    },
    /* more template items */
    ...
}

filter_options=1

The request returns all of the filters (parameters and their values) available for the given search criteria. Note that this may not be used in combination with a template_id.

For keywords that were converted to tags, tags[].inferred=true. The remaining keywords are shown in keywords.refined[].

HTTP request
GET http://api.templatecloud.com/sandbox/templates/?user_key=ba386e729c5f6870cea89f38e92d7a5c&format=json&filter_options=1
&tag_groups=2
HTTP response (JSON)
{
     "colours" : [
        {
            "colour" : "86200e",
            "name" : "Maroon"
        },
         ...
    ],
    "sizes" : [
        {
            "name" : "US Business Card (2x3in)",
            "code" : "USABC",
            "count" : "572",
            "selected" : false, 
            "area" : 7
        },
         ...
    ],
    "tags" : [
            {
            "title" : "Product Types",
            "types" : "PRODUCT",
            "tags" : [
                {
                    "name" : "Appointment Cards",
                    "code" : "194",
                    "count" : "42",
                    "selected" : false,
                    "inferred" : false
                }, 
                 ...
            ]
        }, {
            "title" : "Industry Types",
            "types" : "INDUSTRY",
            "tags" : [
                {
                    "name" : "Arts & Music",
                    "code" : "15",
                    "count" : "688",
                    "selected" : false,
                    "inferred" : true
                },
                 ...
            ]
        }, {
            "title" : "Styles",
            "types" : "STYLE",
            "tags" : [
                {
                    "name" : "Abstract & Illustrative",
                    "code" : "39",
                    "count" : "2406",
                    "selected" : false,
                    "inferred" : false
                }, 
                 ...
            ]
        }, 
         ...
    ]
    "keywords" : {
        "refined" : [
            "test"
        ],
    }
}

Relations

References to templates

  • Use template.tag.tagtype_id to get a tag type:

    Syntax
    /tag_types/<tagtype_id>/
  • Use template.tag.taggroup_id to get a tag group

    Syntax
    /tag_groups/<taggroup_id>/
  • Use template.tag.tag_group.tagtype_id to get a tag type

    Syntax
    /tag_types/<tagtype_id>/
  • Use template.size.name to get a template size

    Syntax
    /template_sizes/<template_size.name>/

Self-relations in /templates/

  • Use template.id to get the single template

    Syntax
    /templates/<template_id>/
  • Use template.tag.taggroup_id to get all templates having that tag group

    Syntax
    /templates/?group_id=<taggroup_id>
  • Use template.designer_id to get all templates by that designer

    Syntax
    /templates/?designer_id=<designer_id>
 

Jump to contents page of

TemplateCloud API Guide

 
 
 

All content is (c) Nettl Systems Limited, 2024 and may not be used, copied or distributed without permission.