source/category/get

Retrieve the available IDML document categories.

An HTTPS GET request sent to:

https://api.datasift.com/v1.6/source/category/get

A successful call to this endpoint returns: 200 OK plus a JSON object.

Parameters

Parameter	Description
page optional	Results page to return. An integer. Defaults to 1. Example values: 1
per_page optional	Results per page. An integer. Defaults to 20. Example values: 10
id optional	Category ID. A string. Example values: interaction, 2545fcac42454c969a01f6b81cf36fac

Examples

1. Listing all public categories with /v1.6/source/category/get:

GET api.datasift.com/v1.6/source/category/get

Output

Success (no id specified) (HTTP Code: 200 OK)

{
    "count": 5,
    "page": 1,
    "pages": 1,
    "per_page": 20,
    "categories": [{
        "id": "2545fcac42454c969a01f6b81cf36fac",
        "version": 4,
        "mapping_id": "557217c8093c44eea00bfeb09c94fae4",
        "mapping_version": 2,
        "name": "Click",
        "schema": "click.duration : int()\r\nclick.date_time : date()\r\nclick.url : url()\r\nclick.domain : string()\r\nclick.title : string()\r\nclick.status_code : int()\r\nclick.content_type : string()\r\nclick.referral_url : url()\r\nclick.referrer : string()\r\nclick.recorded_at : date()\r\nclick.user.id : int()\r\nclick.user.name : string()\r\nclick.user.is_returning : bool()\r\nclick.user.age : int()\r\nclick.user.language : string()\r\nclick.user.gender : string()\r\nclick.user.agent : string()\r\nclick.os : string()\r\nclick.browser.name : string()\r\nclick.browser.version : string()\r\nclick.device.brand : string()\r\nclick.device.format : string()\r\nclick.device.memory : string()\r\nclick.device.model : string()\r\nclick.device.screen.height : string()\r\nclick.device.screen.width : string()\r\nclick.category : string()\r\nclick.location.geo : geo()\r\nclick.location.city : string()\r\nclick.location.country : string()\r\nclick.location.region : string()\r\nclick.cache.status : string()\r\nclick.source : string()\r\nclick.content : string()",
        "metadata": [],
        "visibility": "public",
        "deleted": false,
        "created_at": 1442256409,
        "updated_at": 1443207522,
        "schema_ast": null
    }, {
        "id": "39374e1f0ec345fba2c8a49bf6548e9f",
        "version": 1,
        "mapping_id": "7a645ad8669b4397b9889f79eef01dd5",
        "mapping_version": 1,
        "name": "Email",
        "schema": "email.id : string()\r\nemail.thread_id : string()\r\nemail.subject : string()\r\nemail.content : string()\r\nemail.content_html : string()\r\nemail.summary : string()\r\nemail.content_type : string()\r\nemail.from.name : string()\r\nemail.from.address : string()\r\nemail.to.name : array(string())\r\nemail.to.address : array(string())\r\nemail.cc.name : array(string())\r\nemail.cc.address : array(string())\r\nemail.bcc.name : array(string())\r\nemail.bcc.address : array(string())\r\nemail.labels : array(string())",
        "metadata": [],
        "visibility": "public",
        "deleted": false,
        "created_at": 1443542009,
        "updated_at": 1443542009,
        "schema_ast": null
    }, {
        "id": "653f018695824304a69ebd6155509bd6",
        "version": 1,
        "mapping_id": "1b7171f5b17046a8b1786cae80888a9e",
        "mapping_version": 1,
        "name": "Review",
        "schema": "review.id : string()\r\nreview.type : string().required()\r\nreview.rating : int().required()\r\nreview.content : string().required()\r\nreview.title : string()\r\nreview.source : string()\r\nreview.submitted_at : date()\r\nreview.locale : string()\r\nreview.language : string()\r\nreview.url : url()\r\nreview.author.name : string().required()\r\nreview.author.link : string()\r\nreview.author.id : string()\r\nreview.author.image : string()\r\nreview.author.review_count : int()\r\nreview.reviewed.id : string()\r\nreview.reviewed.name : string()\r\nreview.reviewed.version : string()\r\nreview.reviewed.url : string()\r\nreview.reviewed.type : string()\r\nreview.reviewed.categories : array(string())\r\nreview.reviewed.reviews_count : int()",
        "metadata": [],
        "visibility": "public",
        "deleted": false,
        "created_at": 1442257965,
        "updated_at": 1442257965,
        "schema_ast": null
    }, {
        "id": "49a258e494dc4492902a2933923859f9",
        "version": 1,
        "mapping_id": "af59a827f94b4b28a3cb29f3208a2fd1",
        "mapping_version": 1,
        "name": "Survey",
        "schema": "survey.source : string()\r\n\r\nsurvey.question.id : string()\r\nsurvey.question.content : string()\r\nsurvey.question.type : string()\r\nsurvey.question.options : array(string())\r\nsurvey.question.started_at : date()\r\nsurvey.question.finished_at : date()\r\nsurvey.question.geo : geo()\r\nsurvey.question.validation.min_answers : int()\r\nsurvey.question.validation.max_answers : int()\r\n\r\nsurvey.answer.id : string()\r\nsurvey.answer.content : string()\r\nsurvey.answer.code : string()\r\nsurvey.answer.order : int()\r\nsurvey.answer.choices : array(string())\r\nsurvey.answer.type : string()\r\n\r\nsurvey.respondent.id : string()\r\nsurvey.respondent.name : string()\r\nsurvey.respondent.source : string()\r\nsurvey.respondent.age : int()\r\nsurvey.respondent.sex : string()\r\n\r\nsurvey.meta.id : string()\r\nsurvey.meta.created_at : date()\r\nsurvey.meta.modified_at : date()\r\nsurvey.meta.language : string()\r\nsurvey.meta.subject : string()\r\nsurvey.meta.client : string()\r\nsurvey.meta.operator : string()\r\nsurvey.meta.methodology : string()\r\nsurvey.meta.sample : string()\r\nsurvey.meta.product : string()\r\nsurvey.meta.version : string()\r\n",
        "metadata": [],
        "visibility": "public",
        "deleted": false,
        "created_at": 1442257822,
        "updated_at": 1442257822,
        "schema_ast": null
    }, {
        "id": "6d2420bffa3d4fda9a85ccb47f626890",
        "version": 2,
        "mapping_id": "96ba2199fdad4651a28cdfbcb67ad776",
        "mapping_version": 2,
        "name": "Web",
        "schema": "web.title : string()\r\nweb.link : url()\r\nweb.content : string()\r\nweb.content_html : string()\r\nweb.content_links : array(url())\r\nweb.author.name : string()\r\nweb.author.link : url()\r\nweb.publisher.name : string()\r\nweb.summary : string()\r\nweb.published_at : date()\r\nweb.age : int()\r\nweb.updated_at : date()\r\nweb.meta.categories : array(string())\r\nweb.meta.keywords : array(string())\r\nweb.meta.description : string()",
        "metadata": [],
        "visibility": "public",
        "deleted": false,
        "created_at": 1432650010,
        "updated_at": 1443186710,
        "schema_ast": null
    }]
}

2. Listing a specific category, eg. interaction

GET api.datasift.com/v1.6/source/category/get?id=interaction

Success (id specified, entry exists) (HTTP Code: 200 OK)

{
    "id": "interaction",
    "version": 1,
    "mapping_id": "",
    "mapping_version": 0,
    "name": "schema.interaction",
    "schema": "interaction.type : string().required()\ninteraction.created_at : date() # .default(now())\ninteraction.subtype : string()\ninteraction.media_type : string()\ninteraction.title : string()\ninteraction.content : string()\ninteraction.raw_content : string()\ninteraction.source : string()\ninteraction.geo : geo()\ninteraction.link : url()\ninteraction.author.username : string()\ninteraction.author.name : string()\ninteraction.author.id : int()\ninteraction.author.avatar : url()\ninteraction.author.link : url()\ninteraction.author.language : string()\ninteraction.mentions : array(string())\ninteraction.mention_ids : array(int())\ninteraction.hashtags : array(string())\ninteraction.timezone : string()",
    "metadata": [],
    "visibility": "internal",
    "deleted": false,
    "created_at": 1432214117,
    "updated_at": 1432214117,
    "schema_ast": null
}

Output Fields

Property:	Description:
id	The identity of the category.
version	The version of this copy of the category.
mapping_id	The ID of the mapping it points at.
mapping_version	The version of the mapping it points at.
name	The human-friendly name of the category.
schema	The raw IDML schema.
metadata	Extra metadata held on the category.
visibility	The visibility of this category, it may be internal, public, or private.
deleted	Whether this category has been deleted.
created_at	When this category was created.
updated_atdeleted	When this category was created.
schema_ast	May contain a JSON-serialized AST of the schema.

Notes

1. All calls to the API must be properly authenticated with a DataSift username and API key.
2. All calls to the API must be versioned. The current version is v1.6.

Resource information

Rate limit cost: 5

Requires authentication: Yes

Response formats: JSON, JSONP