Social Media Monitoring API Documentation v2


Introducing API V2

  • Request caching – Requests for the same information within a 30 second period are set to be cached, allowing instant retrieval of unchanged result lists.
  • More filters – Results can now be filtered by sentiment (See the “sentiment” filter below)
  • No forced request structure – Gone is the preset /api_key/keyword/limit/offset/etc/etc/etc/ format, which caused numerous issues for filtering by source when you didn’t want to change the number of results, and other similar issues.

The V2 API query is greatly simplified. If you have no other filters or information you want to input, you can simply use http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=KEYWORD For more specific filtering, you will want to start using some of API V2’s optional parameters.

Required Parameters:

api_key

The API key given to you when you registered for a Trackur API-class membership.
Valid options: Your API Key.

keyword

The keyword you want to get information on.
Valid options: Any string. Unicode support is not running at 100% capacity as of April 2015, but we hope to have it working more reliably in the future.

Optional Parameters:

format

Determines the output format of your data.
Valid options: json, xml
Default: JSON
Examples:
To output in XML instead of JSON:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&format=xml

limit

The number of results to show per page.
Valid options: Any integer 1-1000.
Default: 50
Examples:
To show 100 results per page instead of 50:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&limit=100

offset

Where to start in our result output. Essentially the “next page” option – To see page 1, you would have an offset of 0. To see page 2, you use set the offset to the number of results you are loading per page.
Valid options: Any positive integer.
Default: 0
Examples:
Offset by 50:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&offset=50
Offset by 100 using a non-default limit:

http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&limit=100&offset=100

includes

Other words to require in the result content. Includes require all keywords added to be found in the result content for the result to show up.
If you have three results:
“My boss told me he needs this tomorrow.”
“My boss told me he needs this today.”
“Today, my boss told me he needs this tomorrow.”
And your Includes are “Today,Tomorrow” you would only get the final result.
Valid options: A comma-separated sting of keywords you want to find in your results.
Default: None
Examples:
Using a single include:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=Apple&includes=iPhone
Using multiple includes:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=Apple&includes=iPhone,5C

excludes

Words that you don’t want found in your results. Useful for if you’re searching for a company or product with a common word for a name, but one where said word is usually followed by another word that could be used to filter out those results.
Unlike includes, excludes match for all words.
If you have three results:
“My boss told me he needs this tomorrow.”
“My boss told me he needs this today.”
“Today, my boss told me he needs this tomorrow.”
And your excludes are “Today,Tomorrow” you would not get any of the results.
Valid options: A comma-separated string of keywords that you do not want in your results.
Default: None
Examples:
Using a single exclude:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=Apple&excludes=pie
Using multiple excludes:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=Apple&excludes=pie,cobbler

sources

Sources that you want to get results from that Senfluence/Trackur offer services for.
Valid options: A comma-separated list of valid sources. Valid sources are:

  • Facebook
  • Forums
  • GooglePlus
  • Media
  • News
  • Reddit
  • Reviews
  • Tumblr
  • Twitter

Default: All Sources
Examples:
Using a single source:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&sources=Facebook
Using multiple sources:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&sources=Facebook,twitter

start_time

The start time for the list of your results. With this filter, no results older than the given time will be pulled up.
Valid options: A unix timestamp, or a valid PHP datetime string.
Default: No limit
Examples:
Using a Unix timestamp:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&start_time=1314047490
Using a valid PHP datetime string:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&start_time=April 04, 2015
Using a PHP-parsed string:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&start_time=Last Tuesday

end_time

The end time of your list of results. Generally used in conjunction with start_time to filter for specific days/weeks/months of interest for results.
Valid options: A unix timestamp, or a valid PHP datetime string.
Default: Current time
Examples:
Using a Unix timestamp:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&end_time=1314047490
Using a valid PHP datetime string:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&end_time=April 04, 2015
Using a PHP-parsed string:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&end_time=Last Tuesday
Using start_time and end_time to get a specific week’s results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&start_time=April 04, 2015&end_time=April 11, 2015

influence

If this option is turned on, each result will be given an extra value in its output called “influence.” The result’s influence score represents the source website’s calculated influence based on our in-house Influence and Sentiment API.
This option should be used sparingly – Processing this information for each site is done at request time to ensure the most up-to-date influence scores, and can dramatically slow down response times (especially on queries with larger numbers of results.)
Valid options: 0, False, No, 1, True, Yes
Default: False
Examples: http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&influence=1

New parameters for V2:

timestamp_format

Not all countries use the same time format, and we recognize this. Rather than requiring that you parse our timestamps into a value and then output them into your own, you can simply pass this parameter with a value to have the results printed back in your preferred format.
PLEASE NOTE:Published values will always by output as strings. If you set the timestamps to a Unix timestamp, it will not be counted as an integer by default.
Valid options: Any valid PHP datetime string.
Default: DATE_ISO8601 format (“Y-m-d\TH:i:sO” resulting in 2015-04-13T15:52:01+0000)
Examples:
Giving the published time as a Unix timestamp:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&timestamp=U
Giving the published time as “April 04, 2015”:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&timestamp=F d, Y

sentiment

Filters results based on the calculated sentiment of the results. Negative filtering returns results that have been calculated as having a negative connotation. Conversely, positive filtering will return results that have a positive wording.
PLEASE NOTE:“Neutral” is not the same as the default lack of filtering. Without this filter, the API will return all results regardless of sentiment value. With Neutral filtering, the API will only return results with a neutral wording.
Valid options: -1, Neg, Negative, 0, Neut, Neutral, 1, Pos, Positive
Default: None
Examples:
Requesting only negative results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&sentiment=negative
Requesting only neutral results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&sentiment=0
Requesting only positive results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&sentiment=pos

countries

Filters results based on the language found in the content of them and attempting to connect the language with a global region.
PLEASE NOTE:Less accurate for variants of English (US, UK, AU, NZ, etc.). In many cases, these are simply parsed as “EN.”
Valid options: Any two-letter country/language code (I.E. “EN,” “DE,” “BR”) or comma-separated list of codes (“EN,DE,BR”)
Default: All
Examples:
Requesting only Japanese results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&countries=JA
Requesting only Italian and Brazilian results:
http://api.trackur.com/api/v2/?api_key=YOURKEY&keyword=iPhone&countries=IT,BR

For these samples, some parameters have been purposefully misused with the intention of causing the output to also show how warnings will be displayed.

JSON:

{
    "warnings": [
        "The source 'MySpace' is not supported. Please double-check the documentation. This source has been ignored.",
        "The parameter 'srcs' is not supported. Please double-check the documentation. This parameter has been ignored.",
        "The parameter 'start_date' has been deprecated. Please use 'start_time' instead."
    ],
    "navigation": {
        "current": "http://dev.trackur.com/api/v2/?api_key=demonstration&format=json&keyword=iPhone&limit=2&sources=facebook%2Ctwitter%2CMySpace&srcs=blogs&start_time=last%20tuesday",
        "next": "http://dev.trackur.com/api/v2/?api_key=demonstration&format=json&keyword=iPhone&limit=2&sources=facebook%2Ctwitter%2CMySpace&srcs=blogs&start_time=last%20tuesday&offset=2"
    },
    "user": {
        "results_shown": 8,
        "result_limit": 10000,
        "hourly_requests": 12,
        "hourly_limit": 300
    },
    "request": {
        "request_time": "2015-05-27T16:12:49-0400",
        "format": "json",
        "keyword": "iPhone",
        "limit": 2,
        "offset": 0,
        "includes": [],
        "excludes": [],
        "sources": [
            "Facebook",
            "Twitter"
        ],
        "start_time": "2015-05-26T00:00:00-0400",
        "end_time": "",
        "timestamp_format": null,
        "sentiment": null,
        "countries": []
    },
    "results": [
        {
            "id": "65c0785d314b3009c7d9a40541a81b97",
            "title": "OPINIONS NEEDED PLEASE :) My iphone is too small, and my ipad & samsung tablet is too big -- what is something in... http://t.co/QxBkAAnQ5R",
            "content": "OPINIONS NEEDED PLEASE :) My iphone is too small, and my ipad & samsung tablet is too big -- what is something in... http://t.co/QxBkAAnQ5R",
            "source": "Twitter",
            "published": "2015-05-27T16:11:00-0400",
            "url": "https://twitter.com/TezzA16339724/statuses/603654742355521537",
            "sentiment": 0,
            "location": "EN"
        },
        {
            "id": "8611ca72d5dc08e2cd68e398ab669a6d",
            "title": "'Find My Drunk Friends' app now in iTunes. #findmydrunkfriends #iPad #iPhone http://t.co/7EnSqxfyNx",
            "content": "'Find My Drunk Friends' app now in iTunes. #findmydrunkfriends #iPad #iPhone http://t.co/7EnSqxfyNx",
            "source": "Twitter",
            "published": "2015-05-27T16:11:00-0400",
            "url": "https://twitter.com/Makin_MoneyNow/statuses/603654701385588736",
            "sentiment": 0,
            "location": "EN"
        }
    ],
    "total_results": 2
}

XML:

<response>
    <warnings>
        <item>The source 'MySpace' is not supported. Please double-check the documentation. This source has been ignored.</item>
        <item>The parameter 'srcs' is not supported. Please double-check the documentation. This parameter has been ignored.</item>
        <item>The parameter 'start_date' has been deprecated. Please use 'start_time' instead.</item>
    </warnings>
    <navigation>
        <current>http://dev.trackur.com/api/v2/?api_key=demonstration&format=xml&keyword=iPhone&limit=2&sources=facebook%2Ctwitter%2CMySpace&srcs=blogs&start_time=last%20tuesday</current>
        <next>http://dev.trackur.com/api/v2/?api_key=demonstration&format=xml&keyword=iPhone&limit=2&sources=facebook%2Ctwitter%2CMySpace&srcs=blogs&start_time=last%20tuesday&offset=2</next>
    </navigation>
    <user>
        <results_shown>6</results_shown>
        <result_limit>10000</result_limit>
        <hourly_requests>2</hourly_requests>
        <hourly_limit>300</hourly_limit>
    </user>
    <request>
        <request_time>2015-05-27T16:10:57-0400</request_time>
        <format>xml</format>
        <keyword>iPhone</keyword>
        <limit>2</limit>
        <offset>0</offset>
        <includes></includes>
        <excludes></excludes>
        <sources>
            <item>Facebook</item>
            <item>Twitter</item>
        </sources>
        <start_time>2015-05-26T00:00:00-0400</start_time>
        <end_time></end_time>
        <timestamp_format></timestamp_format>
        <sentiment></sentiment>
        <countries></countries>
    </request>
    <results>
        <item>
            <id>65c0785d314b3009c7d9a40541a81b97</id>
            <title>OPINIONS NEEDED PLEASE :) My iphone is too small, and my ipad & samsung tablet is too big -- what is something in... http://t.co/QxBkAAnQ5R</title>
            <content>OPINIONS NEEDED PLEASE :) My iphone is too small, and my ipad & samsung tablet is too big -- what is something in... http://t.co/QxBkAAnQ5R</content>
            <source>Twitter</source>
            <published>2015-05-27T16:11:00-0400</published>
            <url>https://twitter.com/TezzA16339724/statuses/603654742355521537</url>
            <sentiment>0</sentiment>
            <location>EN</location>
        </item>
        <item>
            <id>8611ca72d5dc08e2cd68e398ab669a6d</id>
            <title>'Find My Drunk Friends' app now in iTunes. #findmydrunkfriends #iPad #iPhone http://t.co/7EnSqxfyNx</title>
            <content>'Find My Drunk Friends' app now in iTunes. #findmydrunkfriends #iPad #iPhone http://t.co/7EnSqxfyNx</content>
            <source>Twitter</source>
            <published>2015-05-27T16:11:00-0400</published>
            <url>https://twitter.com/Makin_MoneyNow/statuses/603654701385588736</url>
            <sentiment>0</sentiment>
            <location>EN</location>
        </item>
    </results>
    <total_results>2</total_results>
</response>