Pinterest Search
Los resultados de Pinterest Search son Pins públicos que coinciden con una consulta de texto, con títulos, descripciones, datos del creador, referencias multimedia, categorías, hashtags, fechas e interacción visible. Estos registros sirven para descubrir temas, investigar temáticas visuales, analizar el contexto de los creadores y comparar contenido a partir de consultas.
Funcionalidades de la Pinterest Search API
- Descubrimiento de Pins por consultaAcepta una consulta de texto no vacía y un results_limit de 1 a 2,000 para solicitar una recopilación acotada de registros de Pins públicos.
- Registros normalizados de Pin, creador y contenido multimediaDevuelve los ID de Pin, las URL, los títulos, el texto, los campos públicos del creador y las referencias de imagen o video en una estructura de resultado coherente.
- Contexto de taxonomía y señales visiblesConserva las categorías, los hashtags, el tipo de Pin, los metadatos de origen, los conteos visibles de Me gusta, comentarios y seguidores del creador, la hora de publicación, la hora de recopilación y el contexto de la consulta enviada, cuando están disponibles.
Parámetros de la Pinterest Search API
| Parámetros | Obligatorio | Descripción |
|---|---|---|
query | Obligatorio | Consulta de texto obligatoria y no vacía que se usa para descubrir Pins públicos de Pinterest; los espacios iniciales y finales se eliminan antes del envío. |
results_limit | Opcional | Cantidad máxima de Pins solicitados para la consulta; el valor predeterminado es 100 y acepta enteros de 1 a 2,000. |
Cómo usar la Pinterest Search API
Envíe una consulta de texto de Pinterest con un límite de resultados, siga la tarea asíncrona y lea los Pins normalizados con paginación por cursor.
- Prepare una consulta de texto no vacía y elija un results_limit de 1 a 2,000.
- Envíe query y results_limit por POST a /v1/pinterest/search y guarde el task_id devuelto.
- Consulte /v1/tasks/{task_id} hasta que la tarea tenga éxito o devuelva un error.
- Lea data.results.items y solicite el next_cursor devuelto mientras has_more siga siendo true.
curl -X POST "https://api.socq.ai/v1/pinterest/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"home office ideas","results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueCasos de uso de la Pinterest Search API
- Conjuntos de datos de Pins por tema: Use una consulta definida con los ID de Pin, las URL de origen, los títulos, el texto, las referencias multimedia y discovery_input para construir una colección temática trazable.
- Investigación visual y de taxonomía: Compare imágenes o videos, post_type, categorías, hashtags, títulos y descripciones para examinar los formatos y temas dentro de los resultados de una consulta.
- Comparación de creadores y señales visibles: Combine los campos públicos del creador con los conteos de Me gusta, comentarios y seguidores, y con collected_at, para comparar el contexto observado de los resultados entre colecciones de consultas.
Consejos de expertos para la Pinterest Search API
- Envíe una consulta no vacía después de eliminar los espacios accidentales alrededor, y mantenga results_limit entre 1 y 2,000 para cumplir la validación de entrada.
- Siga next_cursor hasta que has_more sea false cuando los resultados almacenados superen la primera página de respuesta de 50 elementos.
- Conserve extra.discovery_input y collected_at para que cada Pin siga vinculado a la palabra clave enviada y a la hora de observación.
- Maneje title, text, los datos del autor, media, created_at, categories, hashtags, source y cada métrica como campos opcionales, en lugar de tratar los valores ausentes como errores de la solicitud.
APIs relacionadas
Además de la Pinterest Search API, use estas APIs cuando necesite otro tipo de datos públicos de Pinterest.
- Pinterest Pins API — Convierte URLs de Pins públicos en contenido normalizado, creador, contenido multimedia, taxonomía, marcas de tiempo y métricas visibles.
- Pinterest User Pins API — Descubre Pins públicos desde URLs de perfiles con un límite por perfil, y devuelve contenido normalizado, creador, contenido multimedia, marcas de tiempo y métricas visibles.
- Pinterest Profiles API — Recolecta desde URLs de perfiles la identidad del perfil público, la biografía, la imagen, el sitio web, los conteos visibles de la cuenta y el contexto de recolección.
- Pinterest User Boards API — Lista los tableros de perfiles de Pinterest a partir de sus URL, con nombre, descripción, portada, fecha de creación y conteos de Pins, seguidores, secciones y colaboradores.
- Pinterest Board Pins API — Recolecta los Pins de un tablero de Pinterest a partir de su URL y en el orden del tablero, con el texto del Pin, la cuenta que lo guardó, imágenes en tamaño completo y enlaces a cada Pin.
- Pinterest Topic API — Lee URL de páginas de ideas de Pinterest para obtener las búsquedas mensuales de cada tema, su fecha de actualización y los temas más específicos sugeridos.