twitter4j.api.TrendsResources Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of twitter4j-core Show documentation
A Java library for the Twitter API
There is a newer version: 4.1.2
/*
 * Copyright (C) 2007 Yusuke Yamamoto
 * Copyright (C) 2011 Twitter, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package twitter4j.api;

import twitter4j.*;

/**
 * @author Yusuke Yamamoto - yusuke at mac.com
 * @since Twitter4J 2.1.3
 */
public interface TrendsResources {
    /**
     * Returns the top 10 trending topics for a specific WOEID, if trending information is available for it.

     * The response is an array of "trend" objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Twitter Search, and the Twitter Search URL.

     * This information is cached for 5 minutes. Requesting more frequently than that will not return any more data, and will count against your rate limit usage.

     * 
This method calls https://api.twitter.com/1.1/trends/place.json
     *
     * @param woeid The Yahoo! Where On Earth ID of the location to return trending information for. Global information is available by using 1 as the WOEID.
     * @return trends
     * @throws twitter4j.TwitterException when Twitter service or network is unavailable
     * @see GET trends/place | Twitter Developers
     * @since Twitter4J 3.0.2
     */
    Trends getPlaceTrends(int woeid) throws TwitterException;

    /**
     * Returns the locations that Twitter has trending topic information for. The response is an array of "locations" that encode the location's WOEID (a Yahoo! Where On Earth ID) and some other human-readable information such as a canonical name and country the location belongs in.
     * 
This method calls https://api.twitter.com/1.1/trends/available.json
     *
     * @return the locations
     * @throws twitter4j.TwitterException when Twitter service or network is unavailable
     * @see GET trends/available | Twitter Developers
     * @since Twitter4J 2.1.1
     */
    ResponseList getAvailableTrends() throws TwitterException;

    /**
     * Returns the locations that Twitter has trending topic information for, closest to a specified location.

     * The response is an array of "locations" that encode the location's WOEID and some other human-readable information such as a canonical name and country the location belongs in.

     * A WOEID is a Yahoo! Where On Earth ID.
     * 
This method calls https://api.twitter.com/1.1/trends/closest.json
     *
     * @param location the available trend locations will be sorted by distance to the lat and long passed in. The sort is nearest to furthest.
     * @return the locations
     * @throws twitter4j.TwitterException when Twitter service or network is unavailable
     * @see GET trends/closest | Twitter Developers
     * @since Twitter4J 3.0.2
     */
    ResponseList getClosestTrends(GeoLocation location) throws TwitterException;
}