Skip to content

Anadolu Agency News Flow System API Access and User Guide

1. Creating an API User

To use the API service, you must first log in to https://haber.aa.com.tr using the Master User Account Information sent to your email address by Anadolu Agency (a 7-digit numeric username, e.g., 3001234), and create an API user.

You will use this API user alongside a script or application you develop to automatically download the Anadolu Agency news bulletins you are authorized to access to your own servers. Using the API service does not require any additional permissions, activations, or IP whitelisting; anyone subscribed to Anadolu Agency news via the News Flow System is automatically authorized to use the API.

Creation Steps:
  1. Log in with your Master username and password.
  2. After logging in, click on the "Yönetim" (Management) tab from the upper menu.
  3. On the Management screen, click the "+ Yeni" (+ New) button.
  4. Fill in the required fields (Username, Full Name, Password, Email, End Date) on the new user definition screen, ensure the "Active" checkbox is ticked, and press "Kaydet" (Save).

2. General API Usage Information

To automatically download news, you must send requests to the services hosted at https://api.aa.com.tr using the appropriate parameters based on your subscription agreement (e.g., web and print for photos, web and sd for videos).

  • Methods: The API operates over HTTPS using GET and POST methods.
  • Rate Limiting: There must be a time interval of at least half a second (500 milliseconds) between any two requests made to the API. If this rule is ignored, the API will return an error message. For example, if you fetch photos without waiting, the files will download corrupted; opening the corrupted .jpg as a .txt file will reveal a "try again in 0.XXX sec" error.
  • Authentication: All requests must include the username and password via HTTP_BASIC_AUTH.
  • Format: API responses are strictly in JSON format. All responses contain two main objects: data (the actual payload) and response (status of the request).

3. API Endpoints

The API consists of six main functions.

3.1. Discover Function

Returns the numerical equivalents of the parameters used for searching news categories, priorities, packages, types, languages, and providers. It operates via the GET method. You can append the language_iso parameter to receive the values in specific languages:

  • Turkish: GET /abone/discover/tr_TR
  • English: GET /abone/discover/en_US
  • Arabic: GET /abone/discover/ar_AR
Example cURL: 
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/discover/en_US"
Returned Data Objects:
  • provider: News source (e.g., 1: Anadolu Agency).
  • category: Category (e.g., 1: General, 2: Sports, 3: Economy, 4: Health, 5: Science-Technology, 6: Politics, 7: Culture-Art-Life).
  • priority: Priority (1: Flash, 2: Urgent, 3: Important, 4: Routine, 5: Special, 6: Archive).
  • package: Subscribed bulletin packages (1: General Bulletin, 2: Special Bulletin, etc.).
  • type: News type (1: Text, 2: Photo, 3: Video, 4: File, 5: Graphic).
  • language: Available languages (1: tr_TR, 2: en_US, 3: ar_SA).

3.2. Search Function

Allows you to filter and list news within your authorized subscription packages. This function strictly requires the POST method; using GET will result in an error.

Filter Types:
  1. Date Filters:
    • start_date: Start time. Use * to search from the oldest available record.
    • end_date: End time. Use NOW for the current time.
    • Format: Dates must be in YYYY-MM-DDTHH:NN:SSZ format converted to UTC (GMT+0). For example, 13:45:00 Turkish time on August 30, 2016, is 2016-08-30T10:45:00Z.
  2. Content Filters: Created by prepending filter_ to the objects returned by the Discover function (e.g., filter_category=2). Multiple values can be comma-separated (e.g., filter_category=2,3).
  3. Text Filter: Use the search_string parameter to search for specific words or phrases in the title, summary, or text body (e.g., search_string=Anadolu, Museum).
  4. Pagination Filters: offset (starting record index) and limit (number of records to fetch).
Example cURL (Searching for English text news containing "Dollar"): 
curl -u "api_user:password" -X POST "https://api.aa.com.tr/abone/search" \
  -F "start_date=*" \
  -F "end_date=2016-08-30T21:00:00Z" \
  -F "search_string=Dollar" \
  -F "filter_type=1" \
  -F "filter_language=2"
Response Structure:
  • data.result: Array of found records, including id, type, date (in UTC), title, and group_id.
  • data.total: Total number of records matching the search.

3.3. Subscription Function

Returns information regarding the parameters you are authorized for based on your subscription contract. It operates via the GET method.

Example cURL: 
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/subscription"

Returned Information: Includes details like photo_size (print, web), video_size (sd, web), graph_size (ai, eps, pdf, raster), archive_days, and download_limit (a value of zero means unlimited).

3.4. Document Function

Enables downloading of news, photos, and video files in desired formats using the unique news ID (id) obtained from the Search function. It operates via the GET method.

  • Security: Download links are IP-specific and valid for one day. The server making the API call and the server executing the download must share the same internet exit IP; otherwise, a 403 Forbidden error will occur.
  • Text News: Can be downloaded in NewsML v1.2 (newsml12) and NewsML v2.9 (newsml29) formats.
  • Photos: Can be downloaded in print or web formats based on subscription.
  • Videos: Can be downloaded in sd or web formats based on subscription.
Example cURLs: 
# Downloading Text
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/document/aa:text:20161012:9258343/newsml29"
 
# Downloading a Photo
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/document/aa:picture:20161012:9258465/print"

Requesting a format outside your subscription scope returns a 403 Forbidden error.

3.5. Token Function

Used identically to the Document function but operates via Temporary Redirection (302) to deliver the content. It operates via the GET method.

  • Only accepts size parameters (sd, print, web); it does not respond to newsml12 or newsml29 text requests.
  • The generated redirect link is IP-specific and valid for one day.
  • Integration code must be configured to follow Location headers (HTTP 302 responses).
Example cURL: 
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/token/aa:picture:20161012:9258465/print"

3.6. MultiToken Function

Generates a JSON list containing download links for all content within a photo or video series. It operates via the GET method.

  • Instead of a document ID, you must pass the group_id as a parameter.
  • Only accepts size parameters (sd, print, web); does not respond to newsml12 or newsml29 requests.
Example cURL: 
curl -u "api_user:password" -X GET "https://api.aa.com.tr/abone/multitoken/aa:picturegroup:20190930:19488311/print"