Twitter API

Twitter API는 크게 2가지 분류로 나누어 진다.

1) Search API

The Twitter Search API is a dedicated API for running searches against the real-time index of recent Tweets

=> 트위터 Search API는 최근 트윗들의 실시간 인덱스에 대응하는 검색 전용 API이다.

# 제약사항
a. Search API는 모든 트윗들의 완벽한 인덱스가 아니라 최근 트윗들의 인덱스이다. 6-9일 동안의 트윗들을 포함한다.
b. Search API는 약 1주 이전의 트윗들은 검색 불가능하다.
c. 쿼리들은 복잡성 때문에 제한된다. 만약 그렇게 된다면, Search API는 다음과 같은 에러를 동반한다:  {"error":"Sorry, your query is too complex. Please reduce complexity and try again."}
d. 모든 쿼리는 익명으로 이뤄지므로 검색은 인증을 지원하지 않는다.
e. 검색은 완벽성이 아닌 검색 기능 자체에 포커스를 맞추고 있으므로 몇몇 트윗들이나 사용자가 검색 결과로 부터 누락 될
수 있다. 만약 검색을 완벽히 하고 싶다면 대신, Streaming API를 사용하라.
f. near연산자는 Search API에서 사용될 수 없다. 대신 geocode 파라메터를 사용하라.

# 권장 사항
a. 모든 파라메터들이 적절히 URL encoded되었는지 확인하라.
b. 트윗들을 요청할 때 since_id를 포함하라. 만약 제공하는 since_id가 index가 허용하는 것보다 오래됐다면, 사용 가능한 가장 오래된 since_id가 업데이트 될 것이다.
c. 이 메소드를 사용할 때, 의미있고 유일한 User Agent 문자열을 포함하라. 공유된 호스팅을 사용할 때 자신의 트래픽을 식별하는데 도움이 될 것이다.
d. 검색을 10개의 키워드들과 연산자들로 제한하라.

# 쿼리 작성하기
a. twitter.com/search에 대한 검색을 한다.
b. 해당 URL을 복사한다. 예를 들면, https://twitter.com/#!/search/%40twitterapi.
c. https://twitter.com/#!/search/%40twitterapi를 http://search.twitter.com/search.json?q=로 교체한다.
예를 들면, http://search.twitter.com/search.json?q=%40twitterapi.

# 검색 연산에 대한 참고사항
a. since와 until
- 부정연산(-)을 지원하지 않는다.
- year-month-day 또는 yyyy-mm-dd의 양식으로 입력되어야 한다.
- 00:00 UTC을 기준한다고 간주된다.
- 미래의 시간과 함께 사용될 수 없다. until이 미래에 사용되었다면, HTTP 403에러와 함께 다음과 같은 에러 메시지를
받을 것이다: {"error":"You cannot use an 'until:' date in the future"}. If since is in the future you will receive an HTTP 403 error with the message: {"error":"since_id too recent, poll less frequently"}
b. source
- 딱 하나의 키워드 파라메터와 함께 사용 가능하다. 만약 키워드를 포함하지 않으면 HTTP 403에러와 다음과 같은 에러 메시지를 받을 것이다: {"error":"You must enter a query."}.
- 다중 단어를 공백문자 대신 '_'을 통해 지원한다. 예를 들면, 소스 "Tweet Button"은 다음과 같이 입력 된다 :
source: tweet_button

# Source Metadata
 검색 결과들은 때때로 metadata안에 "recent"나 "popular"값과 함께 result_type필드를 포함한다. "popular" 검색 결과는 트위터가 연산하는 알고리듬에 의해 유도되며, 3개까지 기본 mixed mode에서 나타난다. 또한, 메타데이터에 recent_retweets라 불리는 다른 한 노드를 포함한다. 이 필드는 해당 트윗이 얼마나 많은 리트윗이 발생 했는지를 나타낸다.

2) Streaming API
소개글에서는 다음과 같이 설명해 놓았다.

The Twitter Streaming API allows high-throughput near-realtime access to various subsets of public and protected Twitter data.

=> Twitter Streaming API는 보호되거나 공개된 트위터 데이터의 다양한 서브셋(subset)들에 대한 거의 실시간적 접근을 처리한다.

조금의 의역이 들어가긴 했지만, 의미는 쉽게 전달이 되리라 생각한다. 프로덕트라 불리는 군이 존재 하는데, 목적에 따라 분류를
한 것인듯 싶다.
◎ Product
세 개의 메인 스트리밍 프로덕트(Main Streaming Product)가 존재: The Streaming API, User Streams 그리고 Site Streams.
이 세가지 프로덕트들은 같은 방식으로 동작하지만, 각각은 다소 다른 결과를 제공한다.
a. The Streaming API: 다양한 방법으로 걸러지는 모든 유저들의 공개된 상태: user id, keyword, 무작위 샘플링, 사용자의 위치, 기타.
b. User Streams: 사용자의 정보를 업데이트 하기위한 거의 모든 데이터를 보여준다. 사용자의 OAuth 토큰이 필요하다. 공개되거나 보호되는 팔로잉, 다이렉트 메시지, 멘션 그리고 사용자와 연관된 다른 이벤트들을 제공한다. 많은 수의 사용자 스트림들은 같은 호스트나 서비스로부터 생성되지 않을 것이다. 예를 들면, 동시에 몇개의 계정들을 보여주는 한 응용프로그램은 계정당 하나의 연결만 할 것이다. 주된 용도는 트위터 클라이언트(=트위터 API를 사용하는 응용 프로그램)에게 업데이트(=최근 일어난 이벤트)를 제공하는 것이다.
c. Site Streams: 한 사이트 스트링 연결에 대한 다중 사용자 스트림들의 다중 전송을 한다. 5이상의 사용자 스트림 연결들이 같은 호스트나 서비스로 부터 열리면 사이트 스트림이 사용된다. 주된 목적은 웹 사이트와 다른 서비스간의 통합이다.

◎ Methods
a. statuses/filter
 하나 이상의 필터에서 걸러지는 공개된 상태를 반환한다. 최소 하나의 파라메터, 팔로우, 위치 또는 트랙이 명세 되어야 한다. 여러 개의 파라메터들은 대부분의 클라이언트들이 Streaming API에 대한 단일 연결만을 사용하도록 명세된다. URL에 너무 긴 파라메터들을 두는 것은 거부될 것이다. 따라서, 그 때는 POST 리퀘스트의 헤더 파라메터를 사용하라.
 기본 접근 레벨은 400개의 트랙의 키워드들, 5,000개의 팔로우 사용자 id들 그리고 25 0.1-360 도의 구역 정보 까지 허용한다. 증가된 접근 레벨은 100,000개의 팔로우 사용자 id들("shadow" 역할), 400,000개의 팔로우 사용자들("birddog"역할), 10,000개의 트랙 키워드들("restricted track" 역할), 200,000개의 트랙 키워드들("partner track"역할) 그리고, 200 0.1-360 도의 위치 박스들("locRestricted"역할)을 허용한다. 증가된 트랙 접근 레벨은 또한, 해당 스트림을 제한하기 전보다 더 높은 상태들의 비율을 전달한다.
-URL: http://stream.twitter.com/1/statuses/filter.json
-Method(s): POST
-Parameters: count, delimited, follow, locations, track
-Returns: status element의 스트림

b. statuses/firehose
 모든 공개된 상태들을 반환한다. Firehose는 일반적으로 사용가능한 리소스가 아니다. 소수의 응용프로그램들이 이 레벨의 접근을 사용한다. 다른 리소스들과 다양한 접근 레벨들의 조합의 사용을 창의적으로 하는 것은 거의 모든 응용프로그램의 사용용도에 적합할 것이다.
-URL: http://stream.twitter.com/1/statuses/firehose.json
-Method(s): GET
-Parameters: count, delimited
-Returns: status element의 스트림

c. statuses/links
 http:와 https:를 담고 있는 모든 상태들을 반환한다. 해당 링크 스트림은 일반적인 리소스가 아니다. 소수의 응용프로그램들이 이 레벨의 접근을 사용한다. 다른 리소스들과 다양한 접근 레벨들의 조합의 사용을 창의적으로 하는 것은 거의 모든 응용프로그램의 사용용도에 적합할 것이다.
-URL: http://stream.twitter.com/1/statuses/links.json
-Method(s): GET
-Parameters: count, delimited
-Returns: status element의 스트림

d. statuses/retweet
 모든 리트윗들을 반환한다. 리트윗 스트림은 일반적인 리소스가 아니다. 소수의 응용프로그램들이 이 레벨의 접근을 사용한다. 다른 리소스들과 다양한 접근 레벨들의 조합의 사용을 창의적으로 하는 것은 거의 모든 응용프로그램의 사용용도에 적합할 것이다.
-URL: http://stream.twitter.com/1/statuses/retweet.json
-Method(s): GET
-Parameters: delimited
-Returns: status element의 스트림

e. statuses/sample
 모든 공개된 상태들의 한 무작위 샘플을 반환한다. 기본 접근 레벨, 'Spritzer'는 Firehose의 작은 비율(거의 모든 공개된 상태들의 1%가량)을 제공한다. "Gardenhose" 접근 레벨은 통계학적으로 중요한 샘플이 될 큰 비율을 필요로 하는, 데이터 마이닝과 리서치 응용 프로그램에 더욱 적합한 비율을 제공한다. 현재 "Gardenhose"는 대략 모든 공개 상태들의 10%가량을 반환한다. 이 비율들은 트래픽 정도가 다르기 때문에 공지없이 조정될 수 밖에 없다.
-URL: http://stream.twitter.com/1/statuses/sample.json
-Method(s): GET
-Parameters: count, delimited
-Returns: status element의 스트림

◎ Query Parameters
a. count
 라이브 스트림 딜리버리(live stream delivery)로 바뀌기 전의 딜리버리를 고려하는 이전 상태들의 수를 나타낸다(?). 필터링 되지 않은 스트림들에 대해, 모든 고려되는 상태들이 전달된다. 따라서, 요청되는 수와 반환되는 수는 같다. 필터링 되는 스트림에 대해서는,
요청되는 수는 이용된 필터로 걸러진 상태들의 수와 요청된 수가 같고, 반환된 수와는 다르다.
 모든 상태들을 캡춰하는데 관심이 있는 Firehose, Links, Birddog와 Shaow 클라이언트는 매초 받은 상태들의 수의 현재 추정치를 유지하고 마지막 상태가 도착한 시간을 기록한다. 재 연결시에, 해당 클라이언트는 그때, 요청하는 적절한 백로그(backlog)를 추정할 수 있다. count 파라미터는 트랙, 샘플과 기본 접근 역할(default access role)을 포함한 다른 경우에는 사용될 수 없는 것을 알아 둘것.
Values: -150,000~150,000. 이 범위는 예고 없이 바뀔수 있다. 양수 값들은 라이브 스트림으로 죽~ 변하고 음수 값들은 historical 스트림이 종료될 때 종결된다(디버깅에 용이함).
Methods: statuses/firehose, statuses/links, statuses/filter
b. delimited
 '상태들은 해당 스트림 내에서 범위가 정해져야한다'는 것을 나타낸다. 상태들은 바이트 단위 길이, 개행문자 그리고 정확히 길이 바이트 상태 문자에 의해 표현된다. "keep-alive"한 개행문자들은 각각의 길이 전에 삽입되어 있을 것이다.
Values: length
Methods: statuses/firehose, statuses/links, statuses/filter, statuses/sample, statuses/retweet
Example: 

curl http://stream.twitter.com/1/statuses/sample.json?delimited=length -uAnyTwitterUser:Password

c. follow
 주어진 사용자들의 집합을 참조하는 공개된 상태들을 반환한다. 사용자들의 리스트는 콤마(,)로 분리된다.
일치하는 참조들은 다음과 같은 상태들이다:
- 명세된 사용자로 부터 만들어진
- 명세된 사용자에 의해 만들어진 명시적으로 in-reply-to된 상태(응답 "swoosh"버튼이 눌러진)
- 명세된 유저에 의해 명시적으로 리트윗된(리트윗 버튼이 눌러진)
- 명세된 사용자에 의해 만들어지고 그 이후에 다른 유저로부터 명시적으로 리트윗된
일치하지 않은 참조들은 다음과 같은 상태들이다:
- 멘션들("Hello @user!")
- 암시적인 리트윗들("RT @user Says Helloes" 리트윗 버튼을 누르지 않고)
- 암시적 응답들("@user Hello!", in_reply_to필드를 설정하는 응답 "swoosh"버튼을 누르지 않고 만들어진)
Values: 콤마들로 분리된 사용자 id들(정수)
Methods: statuses/filter
Example:
"follow=12,13,15,16,20,87"을 포함하는 'following'이라 불리는 파일을 만들경우,

curl -d @following http://stream.twitter.com/1/statuses/filter.json -uAnyTwitterUser:Password.

Jeremy를 빼고(private 사용자니까) Jack Biz, Crystal Ev, Krissy로부터의 업데이트를 JSON으로 받을 것이다.

d. track
 추적(track)할 키워드들을 명세한다. 키워드들의 구(phrase)는 콤마로 분리되는 리스트에 의해 명세된다. 쿼리들은 Track Limiting에 묘사된 Track Limitations와 statuses/filter 메소드에 묘사된 접근 역할들에 적용된다.
 콤마로 분리되는 키워드들과 구들은 논리적 OR들이며 구들은 논리적 AND들이다. 구 내부의 단어들은 공백문자로 분리된다.
매치 여부는 한 트윗과 구를 매칭한 결과로 이뤄진다. 이 것은 단어들이 해당 트윗에 모두 있을 경우를 말한다(예를들면, 'the twitter'는
the AND twitter 이고, 'the,twitter'는 the OR twitter이다). 조건들(terms)은 정확하게 매치되고(exact-matched) 또한, 정확하게 매치되는 무시되는 구두점(ignoring punctuation)이다. 각각의 콤마로 구분되는 조건은 60문자까지 허용된다.
 구들(공백문자가 포함된 키워드들)은 토큰들과 유일하게 매치 되도록 강제되고 '#'과 '@'이 앞에 오는 키워드들 외에는 매치되지 않는 경향이 있다. 토큰화가 공백을 기준으로 이루어 지기 때문에, CJK나 아라비아의 그것과 같이 공백으로 구분되지 않는 언어들은 현재 지원되지 않는다. 다른 UTF-8 구들은 정확히 매치 되어야 하지만 그것들의 최소공통분모와 유사한 문자들로 대용되지 않을 것이다.
Track exmples:
- Twitter -> 다음중 하나를 포함하는 상태를 반환: TWITTER, twitter, "Twitter", twitter., #twitter, @twitter.
- Twitter -> TwitterTracker나 http://www.twitter.com을 포함하는 상태는 반환하지 않음.
- helm's-alee -> helm's-alee를 포함하는 상태를 반환.
- helm's-alee -> #helm's-alee를 포함하는 상태를 반환하지 않음.
- twiiter api, twitter streaming -> 다음과 같은 상태들을 반환: "The Twitter API is awesome", "The twitter streaming deal is fast"
- twitter api, twitter streaming -> 다음과 같은 상태들은 반환하지 않음: "I'm new to Twitter".
- chirp search, chirp streaming -> 다음과 같은 상태들을 반환: "Listening to the @chirp talk on search", "I'm at Chirp talking about search!", "loving this search talk #chirp".
Value: 콤마로 분리되는 문자열들. 각 문자열은 1~60자여야 한다.
Methods: statuses/filter
Example:
"track=basketball,football,baseball,footy,soccer"라는 구를 포함하는 'tracking'이라는 파일을 만들 경우,

curl -d @tracking http://stream.twitter.com/1/statuses/filter.json -uAnyTwitterUser:Password.

다양한 결정적인 sportsball 주제들과 이벤트들에 대한 업데이트들을 JSON으로 받을 것이다.

e. location
  추적용 구역 경계들(bounding boxes)의 한 집합을 명세한다. Geotagiing API를 사용해서 만들어지거나 추적되는 구역 경계 내에 위치한 트윗들만 이 스트림에 포함될 것이다 - 해당 사용자의 지역 필드는 트윗을 걸러내는 데 사용되지 않음(예를 들면, 한 유저가 트윗들의 구역 정보를 샌프란시스코로 지정했다 할지라도, 트윗들은 Geotagging API를 사용해서 만들어 지지 않았고 geo 요소를 가지지 않으므로 이 스트림에 포함되지않을 것이다). 구역 경계들은 해당 구역의 남서쪽 코너를 나타내는 값이 첫 번째로 나타나는 위도/경도 쌍들의 콤마로 구분되는 리스트로 명세 된다. 예를 들면 이렇다. locations=-122.75,36.8,-121.75,37.8은 샌프란 시스코 지역으로부터 트윗들을 추적할 것이다. 다수의 구역 경계들은 위도/경도 쌍들을 이음으로써 나타낸다. 예를 들면, locations=-122.75,36.8,-121.75,37.8,-74,40,-73,41은 샌프란시스코와 뉴욕으로부터 트윗을 추적할 것이다.

 단순히 추적 파라메터들을 함께 사용함으로써, 쿼리들은 Track Limiting으로 묘사되는 Track Limitations과 statuses/filter 메소드로 묘사되는 접근 역할에 적용된다. 구역 경계들의 숫자와 크기 둘 다 제한이 된다. 구역 경계에서 경도는 360도까지 위도는180도까지 가능하며 보통 25개 까지의 구역 경계를 명세할 것이다. 360-경도와 180-위도의 한 구역은 지구 전체를 커버한다. 더 높은 접근 레벨들은 추가적인 구역 경계들을 제공한다.
 구역 경계들은 논리적 OR들이다. 한 locations(구역 정보) 파라메터는 추적 파라메터와 함께 조합 될 수 있지만 모든 조건들은 논리적으로 OR이다. 그래서 해당 쿼리 스트링이 'track=twitter&locations=-122.75,36.8,-121.75,37.8'이라면 Twitter 또는(OR) 샌프란시스코 지역으로부터 나오는 트윗들과 매치될 것이다.
 
Values: 콤마로 분리되는 위/경도 쌍들. 해당 구역 정보에서 첫 번째 쌍은 남서쪽 모서리를 나타냄.
Methods: statuses/filter
Example: "locations=-122.75,36.8,-121.75,37.8,-74,40,-73,41"를 포함하는 'locations'라는 이름의 파일을 만들 경우:

curl -d @locations http://stream.twitter.com/1/statuses/filter.json -uAnyTwitterUser:Password.

샌프란시스코와 뉴욕으로 부터 나오는 모든 geo tagged된 트윗을 응답으로 받을 것이다.