API Twitter - POST Method /create

Allows creating new Workers with their words.

What is a Worker?

A Worker in TrawlingWeb is an entity configured by the user to perform specific searches on social networks using Keywords. These Keywords are search terms configured within the Worker and are based on the credits purchased (1 credit = 1 Keyword).

Creating and Configuring Workers

The user can create and define search terms for each Worker directly in the dashboard (https://dashboard.trawlingweb.com/workers) or using the method provided by the API. Once a Worker is created, it begins its deployment to start its configuration process, which can take up to an hour.

Functionality of Workers

• Keywords: Workers function as a list of keywords. They use the configured Keywords to perform searches on social networks.
• Search Process: Workers deliver the Keywords to TrawlingWeb's spiders to execute their searches on the social network.
• Delivery Process: Each time the client calls the Worker, it uses the list of Keywords to launch the search against the database of results obtained by TrawlingWeb and retrieve only those results that are related to the list of Keywords.

Implementing and managing Workers efficiently allows users to maximize the relevance and accuracy of the data processed, adapting to the specific needs of their social media analysis and monitoring.

POST Parameters

Let's see the structure of the example query:

https://twitter.trawlingweb.com/create/?token={APIKEY}

PATH Parameters:

QUERY Parameters:

BODY Parameters:

Structure of the words parameter

The words parameter must be sent as a JSON array of text strings, where each array element represents a Keyword. Each Keyword can contain advanced Twitter syntax (hashtags, mentions, boolean operators, filters, etc.).

Important recommendation for searches with from:: When you need to search for tweets from multiple accounts, you can chain up to a maximum of 10 accounts using the OR operator within a single expression. This allows you to optimize credit usage by grouping multiple accounts into a single Keyword.

Example body in JSON format:

{
  "description": "Example Worker for brand monitoring",
  "words": [
    "from:cocacola OR from:pepsi OR from:trawlingweb",
    "cocacola",
    "#pepsi",
    "cocacola lang:fr",
    "itau geocode:-25.2867,-57.647,250km OR ueno geocode:-25.2867,-57.647,250km OR basa geocode:-25.2867,-57.647,250km",
    "itau geocode:-25.2867,-57.647,250km min_faves:200",
    "cocacola filter:videos min_faves:100",
    "itau geocode:-25.2867,-57.647,250km min_faves:50 -from:itauparaguay"
  ]
}

In this example, the Worker is created with 8 Keywords:

1. A complex search with multiple accounts using the OR operator (maximum 10 accounts per expression)
2. A simple word: "cocacola"
3. A hashtag: "#pepsi"
4. A word with language filter: "cocacola lang:fr"
5. A chained geographic search with multiple terms using geocode and OR
6. A combination of word, geocoding, and popularity filter: "itau geocode:-25.2867,-57.647,250km min_faves:200"
7. A viral video search: "cocacola filter:videos min_faves:100"
8. A search with official account exclusion: "itau geocode:-25.2867,-57.647,250km min_faves:50 -from:itauparaguay"

Each element in the words array consumes 1 credit (1 credit = 1 Keyword).

Output Response - RESPONSE

Once a request is sent to the Twitter API, it will return a response structured as follows:

Status 200 - Return Data

Example response in json format:

"response" : {
    "worker" : "...",
    "msg" : "..."
}

Status 400 - Return Data

Example response in json format:

"response" : {
    "error" : "..."
}

Better searches with Twitter syntax

Twitter uses its own advanced syntax to perform specific and detailed searches within its platform. This syntax allows filtering results by keywords, hashtags, mentions, locations, and dates, among other parameters. Additionally, when defining keywords for a Worker, this same syntax can be used to launch precise queries against Twitter's search engine. This maximizes the efficiency and relevance of the data processed by each Worker, facilitating more effective monitoring and analysis of Twitter conversations.

Here is a list of elements you can combine with your keywords when creating them within a worker, organized by categories:

Basic and Precision Searches

These elements allow you to refine and precisely target your searches by content type, location, accounts, language, and other specific filters:

Popularity Searches

These elements allow you to filter results by number of likes (favorites), useful for finding viral or popular content:

Time Freshness Searches

These elements allow you to filter results by specific dates or time ranges:

Combining Multiple Expressions

One of the most powerful features of Twitter syntax is the ability to combine multiple expressions and filters in a single Keyword. X (Twitter) interprets each space as an implicit AND operator, meaning you can chain different filters simply by separating them with spaces.

Important rules for combining expressions:

1. Separation by spaces (implicit AND): Each space between expressions acts as an "AND also". For example:

   • itau geocode:-25.2867,-57.647,250km min_faves:200 means: "itau" AND geocoded in that location AND with at least 200 likes.

2. No spaces after colons: It is critical that there are no spaces after the colons in commands:

   • ✅ Correct: min_faves:200
   • ❌ Incorrect: min_faves: 200

3. Combining content filters: You can combine content type filters with other parameters:

   • filter:videos - Only tweets with videos
   • filter:images - Only tweets with images
   • filter:links - Only tweets with links

4. Exclusions with minus prefix (-): You can exclude accounts, words, or terms using the minus prefix:

   • -from:account - Excludes tweets from that account
   • -word - Excludes tweets containing that word

Practical examples of combinations:

Search for viral videos in a specific location:

itau geocode:-25.2867,-57.647,250km min_faves:200 filter:videos

Searches for videos about "itau" in Paraguay with at least 200 likes.

Search excluding official accounts:

itau geocode:-25.2867,-57.647,250km min_faves:50 -from:itauparaguay

Searches for mentions of "itau" in Paraguay with at least 50 likes, excluding the official account.

Search within a date range with popularity filter:

itau geocode:-25.2867,-57.647,250km min_faves:100 until:2024-01-01 since:2023-01-01

Searches for mentions of "itau" in Paraguay during 2023 with at least 100 likes.

Search for images in a specific language:

cocacola lang:es filter:images min_faves:20

Searches for images about "cocacola" in Spanish with at least 20 likes.

Note on min_faves and result ordering:

When using min_faves: with a high number, X usually shows results in the "Top" tab automatically. If you switch to "Latest", you'll see tweets that reached that number of likes sorted by date.

Recommendation: If no results appear with a high min_faves:, try lowering the number (for example, min_faves:20 or min_faves:50) to verify that the syntax is correct and that content is available.

Important notes on geographic searches

Geocoding (geocode:): X (Twitter) does not support the country: command or a direct syntax by country code (such as country:es). The most accurate method to filter results by geographic location is to use geocode: with exact GPS coordinates.

Geocode syntax:

• Format: geocode:latitude,longitude,radius
• Example: itau geocode:-25.2867,-57.647,250km searches for mentions of "itau" within a 250km radius from Asunción, Paraguay.
• Coordinates must be in decimal format (latitude,longitude).
• The radius can be specified in kilometers (km) or miles (mi).

Chaining multiple searches with OR: You can combine multiple search terms with geocoding using the OR operator within a single Keyword. This allows you to optimize credit usage by grouping related searches into a single Keyword:

{
  "description": "Worker for geographic search of multiple terms in Paraguay",
  "words": [
    "itau geocode:-25.2867,-57.647,250km OR ueno geocode:-25.2867,-57.647,250km OR basa geocode:-25.2867,-57.647,250km"
  ]
}

This example searches for mentions of "itau", "ueno", or "basa" within a 250km radius from Asunción, Paraguay, using only 1 credit.

Comparison of geographic methods:

• geocode: - Most accurate, requires exact GPS coordinates. Recommended for professional searches.
• near: + within: - Less accurate, works with city names but can be less precise.
• lang: - Filters by tweet language, not by physical location. Useful when the goal is to filter by language rather than location.

Important note: Geographic filters only work with tweets from users who have location enabled in their posts or public profile.

Table of capital city coordinates for geographic searches

Below is a table with GPS coordinates of the main capitals of Latin America and Europe, along with search examples using geocode: and the recommended radius to cover most of each country's territory:

Latin American Capitals

European Capitals

Note: The recommended radii are calculated to cover most of each country's territory. You can adjust the radius according to your specific search needs.

Reserved characters in search words

Reserved characters are: + - = & | > < ! ¡ () {} [] ^ " ~ * ¿ ?: \ / ' -

Contact

If you have any questions, need assistance, want to hire or expand your services, please contact us.

Technical Support (SAT):

• Email SAT
• Official Documentation

Administrative Support (SAC):

• Email SAC

Sales Support:

• Email Sales