• Home /
  • APIs /
  • Search API /
  • Overview
  • Overview


    Gnip’s Search API provides low-latency, full-fidelity, query-based access to 30 days of historical data with minute granularity, with data available within 30 seconds of generation on the Twitter Platform.

    The Search API supports two types of requests – Search Requests and Estimate (Tweet Count) Requests.

    Search Requests

    Search requests to the Search API allow you to retrieve up to the last 500 results for a given timeframe in the last 30 days. It can be used to retrieve the most recent results for a high volume query, all results for a small time slice, or all of the results in the last 30 days for a low volume query. The Search endpoint is ideal for allowing users to search for recent data for a query or topic. Searches can be refined to any timeframe in the last 30 days to analyze the data in that given timeframe. Results provided via Search are compliant at the time of delivery.

    Estimate Requests

    Estimate Requests provide the ability to retrieve historical activity counts, which reflect the number of activities that occurred that match a given query during the requested timeframe. These requests may define bucket sizes for the generation of the counts, which define the time period of each count. The bucket size may be per day, hour, or minute.

    These counts do not reflect any later compliance events (deletions, scrub geos), and some activities which are counted may not be available to retrieve with a Search request due to user compliance actions.

    Query / Rules

    Search supports queries that behave like Gnip’s PowerTrack ‘standard’ rules and utilize the same syntax, described here.

    Note: Only ‘standard’ PowerTrack rules (a maximum of 1,024 characters with up to 30 positive and 50 negative clauses) can be used with the Search API.

    Query/Rule Limitations 

    The Search API does not currently support the following operators:

    • klout_score
    • followers_count
    • friends_count
    • statuses_count
    • listed_count
    • sample
    • contains
    • profile_region_contains
    • profile_locality_contains
    • bio_contains
    • bio_location_contains
    • place_contains
    • bio_name_contains
    • profile_subregion_contains:
    • All is: and has: operators cannot be used as standalone operators and must be “ANDed” together in conjunction with another clause (e.g. @gnip has:links)

    In the Search API, the url_contains operator behaves in a slightly different manner than the equivalent operator in realtime PowerTrack streams. Specifically, url_contains in Search does not act as a pure substring match. In Search, url_contains: must be used with complete words or groups of complete words, but NOT partial words or substrings.

    For example:

    Target URL Matching Rules Non-Matching Rules
    http://blog.gnip.com/search-api-for-twitter/ url_contains:"blog.gnip.com/search-api-for-twitter/"
    url_contains:"gnip.com"
    url_contains:"search-api"
    url_contains:"blog.gnip.com"
    url_contains:"gnip.com/search"
    url_contains:api
    url_contains:twitter
    url_contains:"blog.gnip.com/sea"
    url_contains:"log.gnip.com"
    url_contains:"ip.com"
    url_contains:"ip"



    Continue to the API Reference