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

# Look up Etsy links

> Turn an Etsy listing or shop link, or a shop name, into Alura's data.

`GET /v1/research/lookup` takes an Etsy link in `url`, or a shop name in `name`, and returns the product or shop it points to. It reads the link without opening it.

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body -sS -G https://api.alura.io/v1/research/lookup \
    -H "Authorization: Bearer $ALURA_API_KEY" \
    --data-urlencode "url=https://www.etsy.com/listing/4524717183/personalized-name-mug"
  ```

  ```typescript TypeScript theme={null}
  interface Lookup {
    shop: { id: string; name: string | null } | null;
    product: { id: string; title: string | null; shop: { name: string | null } } | null;
  }

  const links = ['https://www.etsy.com/listing/4524717183/personalized-name-mug', 'https://www.etsy.com/shop/MugCo'];

  for (const link of links) {
    const url = new URL('https://api.alura.io/v1/research/lookup');
    url.searchParams.set('url', link);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}` } });
    if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
    const found = (await res.json()) as Lookup;
    if (found.product) console.log(`product ${found.product.id}: ${found.product.title} (${found.product.shop.name})`);
    if (found.shop) console.log(`shop ${found.shop.id}: ${found.shop.name}`);
  }
  ```

  ```python Python theme={null}
  import json
  import os
  import urllib.parse
  import urllib.request

  links = ["https://www.etsy.com/listing/4524717183/personalized-name-mug", "https://www.etsy.com/shop/MugCo"]

  for link in links:
      request = urllib.request.Request(
          f"https://api.alura.io/v1/research/lookup?{urllib.parse.urlencode({'url': link})}",
          headers={"Authorization": f"Bearer {os.environ['ALURA_API_KEY']}"},
      )
      with urllib.request.urlopen(request) as response:
          found = json.load(response)
      if found["product"]:
          product = found["product"]
          print(f"product {product['id']}: {product['title']} ({product['shop']['name']})")
      if found["shop"]:
          print(f"shop {found['shop']['id']}: {found['shop']['name']}")
  ```
</CodeGroup>

The answer has `shop` and `product`: one is filled, the other is `null`. Each is the same full object as `GET /v1/research/shops/{id}` or `GET /v1/research/products/{id}` returns.

Accepted links, on `https` only:

| Link | Finds |
| - | - |
| `https://www.etsy.com/listing/4524717183/personalized-name-mug`, with or without a language part such as `/de/` | The product |
| `https://www.etsy.com/shop/MugCo` | The shop |
| `https://mugco.etsy.com` | The shop |

Other hosts, links with a port or a user name, short `etsy.me` links and bare numbers answer `400 invalid_request`. To look up by ID, use `GET /v1/research/products/{id}` or `GET /v1/research/shops/{id}`.

`name` matches the shop name exactly, ignoring letter case: `GET /v1/research/lookup?name=mugco` finds MugCo. When a renamed shop leaves two shops with the same name, the answer is `409 conflict` listing both.

`GET /v1/research/lookup` costs 1 API credit when it returns a shop or a product, like opening it directly. A shop or product Alura has never seen is fetched from Etsy, as described in [Freshness and new items](/api-reference/freshness): while fetching is switched off, that answers `503 fetch_unavailable`, free.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.