# Lefties Search Autocomplete Scraper (`pintostudio/lefties-search-autocomplete-scraper`)

The Lefties Search Autocomplete Actor is an Apify actor designed to retrieve search autocomplete suggestions from the Lefties website.

- **URL**: https://beta-securitybyobscurity.apify.com/pintostudio/lefties-search-autocomplete-scraper.md
- **Developed by:** [Pinto Studio](https://beta-securitybyobscurity.apify.com/pintostudio) (community)
- **Categories:** E-commerce, Developer tools, Automation
- **Stats:** 2 total users, 2 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

$4.00 / 1,000 results

This Actor is paid per result. You are not charged for the Apify platform usage, but only a fixed price for dataset items the Actor outputs.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-result

# README

## Lefties Search Autocomplete Actor

### Overview

The **Lefties Search Autocomplete Actor** is an Apify actor designed to retrieve search autocomplete suggestions from the Lefties website. This actor helps you discover popular search terms and trending queries by leveraging Lefties' autocomplete functionality across different regional markets.

### Features

- **Multi-region Support**: Works with 20 different country markets supported by Lefties
- **Fast Autocomplete Retrieval**: Quickly fetches search suggestions based on your input query
- **Structured Output**: Returns organized data with timestamps for easy processing
- **Error Handling**: Robust error management with detailed logging

### Supported Countries

The actor supports the following regional markets:

| Country Code | Country/Region |
|--------------|----------------|
| EG | Egypt |
| ES | Spain |
| IC | Canary Islands |
| IT | Italy |
| MX | Mexico |
| PT | Portugal |
| RO | Romania |
| SA | Saudi Arabia |
| TN | Tunisia |
| TR | Turkey |
| AE | UAE |
| AD | Andorra |
| BH | Bahrain |
| IL | Israel |
| KW | Kuwait |
| MA | Morocco |
| OM | Oman |
| QA | Qatar |
| XE | Ceuta and Melilla |
| JO | Jordan |

### Input Configuration

#### Required Parameters

- **query** (string): The search term you want to get autocomplete suggestions for
  - Example: `"ropa"`, `"shoes"`, `"dress"`
  - Default: `"ropa"`

#### Optional Parameters

- **countryCode** (string): Two-letter country code for the Lefties regional site
  - Default: `"ES"` (Spain)
  - Must be one of the supported country codes listed above

#### Input Schema Example

```json
{
  "query": "ropa",
  "countryCode": "ES"
}
```

### Output Format

The actor returns autocomplete suggestions in a structured format:

#### Main Output Structure

```json
{
  "results": [
    {
      "query": "ropa deportiva"
    },
    {
      "query": "ropa niña"
    },
    {
      "query": "ropa bebe"
    }
  ],
  "completedAt": "2025-06-11T12:51:58.592Z"
}
```

#### Dataset Output

Each autocomplete suggestion is also pushed to the actor's dataset as individual items:

```json
{
  "query": "ropa deportiva"
}
```

#### Key-Value Store

The complete results are saved to the key-value store under the key `"output"` with the following structure:

- **results**: Array of autocomplete suggestions
- **completedAt**: ISO timestamp of when the scraping completed

### Usage Examples

#### Basic Usage

```json
{
  "query": "dress"
}
```

This will search for autocomplete suggestions for "dress" in the default Spanish market.

#### Regional Market Search

```json
{
  "query": "shoes",
  "countryCode": "IT"
}
```

This will search for autocomplete suggestions for "shoes" in the Italian market.

#### Multiple Language Markets

```json
{
  "query": "قميص",
  "countryCode": "SA"
}
```

This will search using Arabic terms in the Saudi Arabian market.

### Error Handling

The actor includes comprehensive error handling:

- **Missing Query**: Throws an error if no search query is provided
- **Invalid Country Code**: Uses default "ES" if an invalid country code is provided
- **Network Errors**: Logs and re-throws network-related errors
- **API Errors**: Handles and logs API response errors

### Performance Notes

- **Speed**: Typically completes within 5-15 seconds depending on network conditions
- **Rate Limiting**: Respects Lefties' server limitations to avoid blocking
- **Concurrent Runs**: Can be run multiple times simultaneously for different queries/regions

### Output Data Usage

The autocomplete data can be used for:

- **SEO Research**: Discover popular search terms in specific markets
- **Market Analysis**: Understand regional shopping preferences
- **Content Strategy**: Identify trending product categories
- **Competitive Intelligence**: Monitor popular search patterns

### Best Practices

1. **Query Selection**: Use relevant base terms for your industry or product category
2. **Regional Targeting**: Choose appropriate country codes for your target markets
3. **Data Processing**: Process results to remove duplicates if running multiple similar queries
4. **Rate Management**: Avoid excessive concurrent runs to prevent IP blocking

### Troubleshooting

#### Common Issues

1. **No Results Returned**
   - Check if the query is too specific or uncommon
   - Verify the country code is correct and supported
   - Try with a more general search term

2. **Actor Fails to Start**
   - Ensure the query parameter is provided
   - Check that the country code is from the supported list

3. **Partial Results**
   - This is normal behavior; autocomplete systems return varying numbers of suggestions
   - Results depend on the popularity and relevance of the search term

#### Debug Information

The actor provides detailed console logging:

- Search query and country confirmation
- Number of results found
- Completion status and timing
- Error details if issues occur

### Technical Details

- **Runtime**: Node.js
- **Memory Requirements**: Minimal (128MB sufficient)
- **Typical Runtime**: 5-15 seconds
- **Output Format**: JSON
- **Data Storage**: Apify Dataset and Key-Value Store

### Support

If you have any questions or encounter any issues, please consult the Apify documentation or reach out to us through one of the following channels:

- **Telegram**: [@pintoflow](https://t.me/pintoflow)
- **Email**: <pintoflowpt@gmail.com>
- **Apify Platform**: You can also contact us directly through this platform.

***

# Actor input Schema

## `query` (type: `string`):

Search term for items

## `countryCode` (type: `string`):

Two-letter country code for LEFTIES regional site

## Actor input object example

```json
{
  "query": "ropa",
  "countryCode": "ES"
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "ropa",
    "countryCode": "ES"
};

// Run the Actor and wait for it to finish
const run = await client.actor("pintostudio/lefties-search-autocomplete-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "ropa",
    "countryCode": "ES",
}

# Run the Actor and wait for it to finish
run = client.actor("pintostudio/lefties-search-autocomplete-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "ropa",
  "countryCode": "ES"
}' |
apify call pintostudio/lefties-search-autocomplete-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=pintostudio/lefties-search-autocomplete-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Lefties Search Autocomplete Scraper",
        "description": "The Lefties Search Autocomplete Actor is an Apify actor designed to retrieve search autocomplete suggestions from the Lefties website.",
        "version": "0.0",
        "x-build-id": "BNsXMsPqz0T4swuCK"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/pintostudio~lefties-search-autocomplete-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-pintostudio-lefties-search-autocomplete-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/pintostudio~lefties-search-autocomplete-scraper/runs": {
            "post": {
                "operationId": "runs-sync-pintostudio-lefties-search-autocomplete-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/pintostudio~lefties-search-autocomplete-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-pintostudio-lefties-search-autocomplete-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "query"
                ],
                "properties": {
                    "query": {
                        "title": "Search Query",
                        "type": "string",
                        "description": "Search term for items"
                    },
                    "countryCode": {
                        "title": "Country Code",
                        "enum": [
                            "EG",
                            "ES",
                            "IC",
                            "IT",
                            "MX",
                            "PT",
                            "RO",
                            "SA",
                            "TN",
                            "TR",
                            "AE",
                            "AD",
                            "BH",
                            "IL",
                            "KW",
                            "MA",
                            "OM",
                            "QA",
                            "XE",
                            "JO"
                        ],
                        "type": "string",
                        "description": "Two-letter country code for LEFTIES regional site",
                        "default": "ES"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
