Top US State

The top US States out of the posts mentioning the term, order by frequency. This information is gathered using a combination of the user’s location field, and geo data, if it is turned on.


Request - Required Parameters

  • app_id (STRING) - Eight Digit ID [ex: 84d8620b]
  • app_key (STRING) - Thirty-two digit key [ex: 281014ad8b0fba5adcc88fac7d79999c]
  • Post app registration, your app id and key can be viewed by going to and clicking "view"

Time Period - Only two of three of these need to be used in a string. First & Last, First & Count, or Last & Count. Last & Count will return results the easiest.

  • first (STRING) - Defines the start of the time period. If January 1 2012 to February 21, 2012 was the specification required, start with specifying the the first time point with first=2011-01-01. Alternatively, say the specification was between yesterday and today.
    • Example(s): first=2011-01-01 first=1323466328 or first=yesterday
  • last (STRING) - Defines the end of a time period. To continue the example above, if the date range specified is January 1, 2012 to February 21, 2011, specify last=2011-02-21. Alternatively say the time period you always wanted to measure was today. One could specify last=today, and then use count to specify 14, 30, up to 1000 days back relative to the time range enabled for the account on the API.
    • Example: last=2012-02-21 or last=1318195928 OR OR last=yesterday OR last=today
  • count (STRING) - Count is used as a period proxy to specified time periods. The standard time period is a day, so using count, you would specify the last 30, 60, 90, 100, to 1000 days by specifying last=today & count=30 (or another period length).
    • Example: count=1 OR 10 OR 100 OR 1000 to specify the time period backward or forward
  • source (STRING) - source=twitter
  • term (STRING) - Parameter description (values: @Name, Keyword, Multiple Keywords, #Hashtag, Phrase, or Post) - See Appendix 1: Term Structures for all terms
  • Request - Option Parameters

    • period (STRING) - Integer of the number of seconds that a period constitutes if "count" is specified rather than a start/end date.
      • Default setting: period=86400 (24 hours x 60 minutes x 60 seconds) or one Day
        • Day: Count=30 (30 days)
          • Example: &first=yesterday&count=30 - Specifies chart or histogram to return 30 days (periods) of data with reference to default period setting
        • Hour: Specify period=3600 (60 minutes x 60 seconds) & Count=24 (hours)
          • Example date setting: &first=1323468000&count=24&period=3600 - Returns 1 day of data by hour
    • limit (STRING)- Limit search results to the specified number. Limit=20 will only return 20 data points and can be used in histograms or charts.
    • number (STRING) - Specifies number of items in non-histogram queries. If the parameter &number=10, the query will only return 10 data points.
    • reverse (STRING) - When set to reverse=true, this will reverse the order of the histograms, charts.
    • output (STRING) - Set to output=csv to return in csv format

    Request - Sample URL


    Relational to state / Area list defined. May use limit to specify number returned; to execute add &limit=#

    Response - Fields

    1. Area (STRING) - Specification of US Area returned in State Code. For reference please visit Appendix 2: Locations.
    2. frequency(STRING) - Frequency of mentions within US Area
    3. status (STRING) - The status of your request (values: submitted, processing, waiting (rarely), complete)

    Sample Response

    { "data": [ [ "CA", 4303 ], [ "NY", 3846 ], [ "FL", 2290 ], [ "PA", 1978 ], [ "TX", 1943 ], [ "IL", 1920 ], [ "None", 1636 ], [ "OH", 1405 ], [ "MI", 1344 ], [ "NC", 1291 ] ], "id": "999-c4ec02ba2048b6e0ad00d8ab02fbc7c7", "request": { "app_id": "c320b773", "app_key": "cfcfd9ea504c25e401bf81bad9f52e92", "count": 30, "external": true, "last": 1321574400, "name": "top-usarea", "number": 10, "source": "twitter", "term": "pepsi" }, "status": "complete" }

    PHP Code Sample

    Python Code Sample

    Ruby Code Sample