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!")

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}}]

...
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. 
curl -X GET "https://api.globalwebindex.com/v3/taxonomy" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
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 in API reference. 
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!")

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}}]

...