> ## Documentation Index
> Fetch the complete documentation index at: https://api.globalwebindex.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Find the Right Question

When working with GWI's API, the first step is to identify the right question from the available categories and
questions. To achieve this efficiently, you can:

1. Retrieve the full taxonomy from GWI’s API.
2. Cache the taxonomy locally for quick and repeated access.
3. Search through the taxonomy to pinpoint the relevant questions.

This use case demonstrates how to navigate GWI's taxonomy, which is structured hierarchically into categories and
questions.

### Step 1: Retrieve the Full Taxonomy

To get the entire GWI taxonomy, you can call the `/v3/taxonomy` endpoint. This endpoint returns all categories, questions,
datapoints and suffixes in the structured format of JSON Lines.

<CodeGroup>
  ```bash Retrieve Full Taxonomy theme={null}
  curl -X GET "https://api.globalwebindex.com/v3/taxonomy" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

### Step 2: Cache Locally

Since the GWI taxonomy doesn’t change frequently, caching it locally will significantly improve performance and save
repeated API calls. You can store this data into a file for future use with a Python script.

### Step 3: Search Questions

To find relevant questions, you can search through the cached taxonomy with keywords (e.g., "social media").
In the given example, the script iterates through all objects in the taxonomy file, i.e., categories, and checks all
their child questions' names and descriptions for the input keyword.

Alternatively, feel free to take a look at the dedicated
[search questions endpoint](/platform-api/reference/questions/v3-questions-search) in API reference.

<RequestExample>
  ```python Cache Locally theme={null}
  import requests
  import json

  headers = {"Authorization": "Bearer YOUR_API_KEY"}

  # Fetch the taxonomy, stream into a JSON Lines file
  with requests.get("https://api.globalwebindex.com/v3/taxonomy", headers=headers, stream=True) as response:
      response.raise_for_status()  # Check for error status
      with open("gwi_taxonomy.jsonl", "w") as file:  # Open a file for caching
          buffer = ""  # Initialize a buffer
          for chunk in response.iter_content(chunk_size=8192):  # Iterate over response chunks
              buffer += chunk.decode('utf-8', errors='ignore')  # Add decoded chunk to buffer
              while True:
                  try:
                      obj, index = json.JSONDecoder().raw_decode(buffer)  # Get 1st object & its end index
                      file.write(json.dumps(obj) + "\n")  # Write object, add line break
                      buffer = buffer[index:].lstrip()  # Remove object from buffer
                  except ValueError:  # - If no object is found
                      break  # add another chunk to buffer

  print("Taxonomy cached successfully!")
  ```

  ```python Search Questions theme={null}
  import json

  taxonomy = []
  with open("gwi_taxonomy.jsonl", "r") as file:
      for line in file:
          taxonomy.append(json.loads(line))


  def search_questions(tax, keyword):
      results = []
      for category in tax:
          if 'category' in category and 'child_questions' in category['category']:
              for q in category['category']['child_questions']:
                  if keyword.lower() in q['name'].lower() or keyword.lower() in q['description'].lower():
                      results.append(q)
      return results


  search_results = search_questions(taxonomy, "social media")

  for question in search_results:
      print(f"Question Code: {question['question']}")
      print(f"Name: {question['name']}")
      print(f"Description: {question['description']}")
      print(f"Namespace: {question['namespace_code']}")
      print()
  ```

  ```python Find Question by Code theme={null}
  import json

  taxonomy = []
  with open("gwi_taxonomy.jsonl", "r") as file:
      for line in file:
          taxonomy.append(json.loads(line))


  def find_question(tax, question_code):
      for category in tax:
          if 'category' in category and 'child_questions' in category['category']:
              for q in category['category']['child_questions']:
                  if q['question'] == question_code:
                      return q
      return None


  found_question = find_question(taxonomy, "q42010")

  print(f"Question Code: {found_question['question']}")
  print(f"Name: {found_question['name']}")
  print(f"Description: {found_question['description']}")
  print(f"Namespace: {found_question['namespace_code']}")
  ```
</RequestExample>

<ResponseExample>
  ```plaintext Search "social media" theme={null}
  Question Code: q47a
  Name: Reasons for Using Social Media (To Q3 2020)
  Description: What are your main reasons for using social media?
  Namespace: core
  Datapoints: [{'datapoint': 'q47a_17', 'name': 'To organize social events (To Q3 2016)', 'order': {'value': 17}}, {'datapoint': 'q47a_11', 'name': 'To follow celebrities / celebrity news', 'order': {'value': 4}}, {'datapoint': 'q47a_6', 'name': 'To find funny or entertaining content', 'order': {'value': 3}}, {'datapoint': 'q47a_9', 'name': 'Because a lot of my friends are on them'}, {'datapoint': 'q47a_8', 'name': 'To fill up spare time', 'order': {'value': 2}}, {'datapoint': 'q47a_4', 'name': 'To meet new people', 'order': {'value': 6}}, {'datapoint': 'q47a_16', 'name': 'To network for work', 'order': {'value': 7}}, {'datapoint': 'q47a_14', 'name': 'To research / find products to buy', 'order': {'value': 9}}, {'datapoint': 'q47a_5', 'name': 'To share photos or videos with others', 'order': {'value': 12}}, {'datapoint': 'q47a_7', 'name': 'To stay up-to-date with news and current events', 'order': {'value': 14}}, {'datapoint': 'q47a_19', 'name': 'To watch / follow sports events', 'order': {'value': 15}}, {'datapoint': 'q47a_12', 'name': 'They are just one of the sites I always tend to visit (To Q3 2016)', 'order': {'value': 16}}, {'datapoint': 'q47a_15', 'name': 'To promote my work (To Q3 2016)', 'order': {'value': 18}}, {'datapoint': 'q47a_2', 'name': 'To share my opinion', 'order': {'value': 11}}, {'datapoint': 'q47a_3', 'name': "To share details of what I'm doing in my daily life", 'order': {'value': 10}}, {'datapoint': 'q47a_1', 'name': 'To stay in touch with what my friends are doing', 'order': {'value': 13}}, {'datapoint': 'q47a_10', 'name': 'General networking with other people', 'order': {'value': 1}}, {'datapoint': 'q47a_13', 'name': "To make sure I don't miss out on anything", 'order': {'value': 5}}, {'datapoint': 'q47a_18', 'name': 'To promote / support charitable causes', 'order': {'value': 8}}]

  Question Code: q42011
  Name: Named Social Media / Messaging Services Used
  Description: How often do you visit or use these services?
  Namespace: core
  Datapoints: [{'datapoint': 'q42011_7', 'name': 'Likee (Select Markets Only)', 'order': {'value': 368}}, {'datapoint': 'q42011_31', 'name': 'Snapchat', 'order': {'value': 386}}, {'datapoint': 'q42011_48', 'name': 'Telegram Messenger', 'order': {'value': 390}}, {'datapoint': 'q42011_35', 'name': 'Viadeo (Select Markets Only)', 'order': {'value': 396}}, {'datapoint': 'q42011_44', 'name': 'Skype', 'order': {'value': 385}}, {'datapoint': 'q42011_32102', 'name': 'Clubhouse', 'order': {'value': 349}}, {'datapoint': 'q42011_18', 'name': 'Inke (China Only)', 'order': {'value': 359}}, {'datapoint': 'q42011_34', 'name': 'TikTok', 'order': {'value': 393}}, {'datapoint': 'q42011_38', 'name': 'Gadu-Gadu (GG) (Poland Only)', 'order': {'value': 356}}, {'datapoint': 'q42011_43', 'name': 'LINE', 'order': {'value': 369}}, {'datapoint': 'q42011_22103', 'name': 'ShareChat (India Only)', 'order': {'value': 382}}, {'datapoint': 'q42011_46', 'name': 'SOMA Messenger (Egypt Only)', 'order': {'value': 387}}, {'datapoint': 'q42011_49', 'name': 'Tencent QQ (China Only)', 'order': {'value': 391}}, {'datapoint': 'q42011_36', 'name': 'Yizhibo (China Only)', 'order': {'value': 406}}, {'datapoint': 'q42011_55', 'name': 'Apple iMessage', 'order': {'value': 342}}, {'datapoint': 'q42011_58', 'name': 'Signal (Select Markets Only)', 'order': {'value': 383}}, {'datapoint': 'q42011_54', 'name': 'Zalo (Vietnam Only)', 'order': {'value': 407}}, {'datapoint': 'q42011_21', 'name': "Copains d'Avant (France Only)", 'order': {'value': 350}}, {'datapoint': 'q42011_42105', 'name': 'Yalla (Egypt, Saudi Arabia and UAE Only)', 'order': {'value': 405}}, {'datapoint': 'q42011_56', 'name': 'Byte (Select Markets Only)', 'order': {'value': 347}}, {'datapoint': 'q42011_19', 'name': '5channel (Japan Only)', 'order': {'value': 341}}, {'datapoint': 'q42011_57', 'name': 'Discord', 'order': {'value': 352}}, {'datapoint': 'q42011_2', 'name': 'Bigo (UAE Only)', 'order': {'value': 345}}, {'datapoint': 'q42011_28', 'name': 'Odnoklassniki (Russia Only)', 'order': {'value': 377}}, {'datapoint': 'q42011_32101', 'name': 'MX TakaTak (India Only)', 'order': {'value': 374}}, {'datapoint': 'q42011_42218', 'name': 'BeReal (Select Markets Only)', 'order': {'value': 344}}, {'datapoint': 'q42011_4', 'name': 'Helo (India Only)', 'order': {'value': 357}}, {'datapoint': 'q42011_8', 'name': 'Meipai (China Only)', 'order': {'value': 372}}, {'datapoint': 'q42011_22316', 'name': 'Mastodon', 'order': {'value': 371}}, {'datapoint': 'q42011_41', 'name': 'Kakao Talk (South Korea Only)', 'order': {'value': 362}}, {'datapoint': 'q42011_42', 'name': 'kik Messenger', 'order': {'value': 363}}, {'datapoint': 'q42011_51', 'name': 'WeChat', 'order': {'value': 400}}, {'datapoint': 'q42011_1', 'name': 'Badoo (To Q2 2024)', 'order': {'value': 408}}, {'datapoint': 'q42011_12101', 'name': 'Triller (USA Only)', 'order': {'value': 394}}, {'datapoint': 'q42011_12373', 'name': 'WeAre8 (Australia, UK and USA Only)', 'order': {'value': 399}}, {'datapoint': 'q42011_9', 'name': 'Neighbourly (New Zealand Only)', 'order': {'value': 375}}, {'datapoint': 'q42011_16', 'name': 'Xiaohongshu (China, Malaysia and Singapore Only)', 'order': {'value': 403}}, {'datapoint': 'q42011_32103', 'name': 'Chingari (India Only)', 'order': {'value': 348}}, {'datapoint': 'q42011_6', 'name': 'KakaoStory (South Korea Only)', 'order': {'value': 361}}, {'datapoint': 'q42011_32213', 'name': 'Koo (Bulgaria and India Only)', 'order': {'value': 364}}, {'datapoint': 'q42011_26', 'name': 'LinkedIn', 'order': {'value': 370}}, {'datapoint': 'q42011_27', 'name': 'Nextdoor (Select Markets Only)', 'order': {'value': 376}}, {'datapoint': 'q42011_10', 'name': 'nk.pl (Poland Only, to Q2 2023)', 'order': {'value': 409}}, {'datapoint': 'q42011_47', 'name': 'Tango', 'order': {'value': 388}}, {'datapoint': 'q42011_50', 'name': 'Viber', 'order': {'value': 397}}, {'datapoint': 'q42011_32104', 'name': 'Moj (India Only)', 'order': {'value': 373}}, {'datapoint': 'q42011_13', 'name': 'Tumblr', 'order': {'value': 395}}, {'datapoint': 'q42011_25', 'name': 'Instagram', 'order': {'value': 360}}, {'datapoint': 'q42011_14', 'name': 'X', 'order': {'value': 402}}, {'datapoint': 'q42011_5', 'name': 'Imgur', 'order': {'value': 358}}, {'datapoint': 'q42011_30', 'name': 'Reddit', 'order': {'value': 381}}, {'datapoint': 'q42011_32112', 'name': 'Kuaishou (Select Markets Only)', 'order': {'value': 365}}, {'datapoint': 'q42011_20', 'name': 'Baidu Tieba (China Only)', 'order': {'value': 343}}, {'datapoint': 'q42011_29', 'name': 'Qzone (China Only)', 'order': {'value': 380}}, {'datapoint': 'q42011_17', 'name': 'XING (Austria and Germany Only)', 'order': {'value': 404}}, {'datapoint': 'q42011_53', 'name': 'WhatsApp', 'order': {'value': 401}}, {'datapoint': 'q42011_45', 'name': 'SNOW (Select Markets Only) (Up to Q2 2022)', 'order': {'value': 410}}, {'datapoint': 'q42011_40', 'name': 'Houseparty (To Q2 2021)', 'order': {'value': 411}}, {'datapoint': 'q42011_15', 'name': 'VK (Russia & Czech Republic Only)', 'order': {'value': 398}}, {'datapoint': 'q42011_42397', 'name': 'Threads', 'order': {'value': 392}}, {'datapoint': 'q42011_32', 'name': 'Taringa (Select Markets Only)', 'order': {'value': 389}}, {'datapoint': 'q42011_3', 'name': 'Facebook', 'order': {'value': 354}}, {'datapoint': 'q42011_12205', 'name': 'Kumu (Philippines Only)', 'order': {'value': 366}}, {'datapoint': 'q42011_22326', 'name': 'Dewu (China Only)', 'order': {'value': 351}}, {'datapoint': 'q42011_32433', 'name': 'Quora', 'order': {'value': 379}}, {'datapoint': 'q42011_11', 'name': 'Pinterest', 'order': {'value': 378}}, {'datapoint': 'q42011_32449', 'name': 'BlueSky', 'order': {'value': 346}}, {'datapoint': 'q42011_22413', 'name': 'Lemon8 (Select Markets Only)', 'order': {'value': 367}}, {'datapoint': 'q42011_12', 'name': 'Sina Weibo (China Only)', 'order': {'value': 384}}, {'datapoint': 'q42011_37', 'name': 'Facebook Messenger', 'order': {'value': 355}}, {'datapoint': 'q42011_23', 'name': 'Douyin Huoshan (China Only)', 'order': {'value': 353}}]
  Suffixes: [{'suffix': '2', 'name': 'Daily', 'order': {'value': 2}}, {'suffix': '1', 'name': 'More than once a day', 'order': {'value': 1}}, {'suffix': '3', 'name': 'Weekly', 'order': {'value': 3}}, {'suffix': '4', 'name': 'Monthly', 'order': {'value': 4}}]

  ...
  ```

  ```plaintext Find "q42010" theme={null}
  Question Code: q42010
  Name: Social Media Awareness
  Description: Which of these have you heard of?
  Namespace: core
  Datapoints: [{'datapoint': 'q42010_13', 'name': 'Tumblr', 'order': {'value': 7}}, {'datapoint': 'q42010_14', 'name': 'X', 'order': {'value': 8}}, {'datapoint': 'q42010_3', 'name': 'Facebook'}, {'datapoint': 'q42010_25', 'name': 'Instagram', 'order': {'value': 1}}, {'datapoint': 'q42010_34', 'name': 'TikTok', 'order': {'value': 6}}, {'datapoint': 'q42010_999', 'name': 'None of these', 'order': {'value': 11}}, {'datapoint': 'q42010_26', 'name': 'LinkedIn', 'order': {'value': 2}}, {'datapoint': 'q42010_11', 'name': 'Pinterest', 'order': {'value': 3}}, {'datapoint': 'q42010_30', 'name': 'Reddit', 'order': {'value': 4}}, {'datapoint': 'q42010_31', 'name': 'Snapchat', 'order': {'value': 5}}]
  ```
</ResponseExample>