Skip to main content

The package is archived. Client for several IKEA's APIs

Project description

The project is archived.


Client for several IKEA APIs.

Test Python Downloads

Features

With this library you can access following IKEA's APIs:

  • Cart,
  • Home Delivery and Collect Services (actually, Order Capture),
  • Items info (2 services),
  • 3D models,
  • Purchases (history and order info),
  • Search,
  • Stock.

Also the package:

  • Is backend agnostic: choose HTTP library you want (async, too!),
  • Is fully typed and tested,
  • Has optional wrappers around some APIs based on Pydantic.

Installation

pip install ikea_api
  • Use httpx — awesome async HTTP library — as backend:
pip install "ikea_api[httpx]"
pip install "ikea_api[requests]"
  • Use wrappers:
pip install "ikea_api[wrappers]"
  • Install everything:
pip install "ikea_api[all]"

Usage

ikea_api is unusual API client. It decouples I/O from logic for easier testing and maintenance. As a bonus, you can use literally any HTTP library. Let's have a look at how to work with ikea_api.

import ikea_api

# Constants like country, language, base url
constants = ikea_api.Constants(country="us", language="en")
# Search API
search = ikea_api.Search(constants)
# Search endpoint with prepared data
endpoint = search.search("Billy")

As you can see, nothing happened up to this point. Code suggests that we already should get the result of the search but we don't. What happened is search() returned a data class that contains information about endpoint that can be interpreted by an endpoint runner. There are two built-in: for requests (sync) and httpx (async), but you can easily write one yourself.

Here's how you would use requests one:

ikea_api.run(endpoint)

And httpx one:

await ikea_api.run_async(endpoint)

ikea_api.run_async() is async function, so you have to "await" it or run using asyncio.run().

Endpoints reference

🔑 Authorization

First time you open ikea.com, guest token is being generated and stored in cookies. Same thing must be done in here before using any endpoint.

This token expires in 30 days.

ikea_api.Auth(constants).get_guest_token()

Previously you could login as user (with login and password), but now there's very advanced telemetry that I wouldn't be able to solve in hundred years 🤪

🛒 Cart

With this endpoint you can do everything you can using IKEA's frontend:

cart = ikea_api.Cart(constants, token=...)
  • Show the cart
cart.show()
  • Clear it
cart.clear()
  • Add, update and delete items
cart.add_items({"30457903": 1})  # { item_code: quantity }

cart.update_items({"30457903": 5})

cart.remove_items(["30457903"])
  • Set and clear coupon
cart.set_coupon(...)

cart.clear_coupon()
  • and even copy another user's cart.
cart.copy_items(source_user_id=...)

You can edit your user's actual cart if you use authorized token (copy-paste from cookies).

💡 There's wrapper that clears current cart and adds items with error handling: if requested item doesn't exist, the function just skips it and tries again.

ikea_api.add_items_to_cart(  # Function returns items that can't be added. In this case: ['11111111']
    cart=cart,
    items={
        "30457903": 1,
        "11111111": 2,  # invalid item that will be skipped
    },
)

🚛 Order Capture

Check pickup or delivery availability. If you need to know whether items are available in stores, use Item availability endpoint or ikea-availability-checker.

order = ikea_api.OrderCapture(constants, token=token)

cart_show = run(cart.show())
items = ikea_api.convert_cart_to_checkout_items(cart_show)

checkout_id = run(order.get_checkout(items))
service_area_id = run(
    order.get_service_area(
        checkout_id,
        zip_code="02215",
        state_code="MA",  # pass State Code only if your country has them
    )
)
home_services = run(order.get_home_delivery_services(checkout_id, service_area_id))
collect_services = run(
    order.get_collect_delivery_services(checkout_id, service_area_id)
)

💡 You can use wrapper to add items to cart (clearing cart before and handling unknown item errors if they appear) and parse response in nice Pydantic models:

services = await ikea_api.get_delivery_services(
    constants=constants,
    token=...,
    items={
        "30457903": 1,
        "11111111": 2,  # invalid item that will be skipped
    },
    zip_code="101000",
)
services.delivery_options  # List of parsed delivery services
services.cannot_add  # ['11111111']

📦 Purchases

purchases = ikea_api.Purchases(constants, token=token)

History

This method requires authentication, so if you don't have authorized token, it won't work.

purchases.history()

# Get all purchases:
purchases.history(take=10000)

# Pagination:
purchases.history(take=10, skip=1)

💡 Get parsed response with the wrapper:

ikea_api.get_purchase_history(purchases)  # Returns a list of parsed purchases

Order info

purchases.order_info(order_number=..., email=...)

# If you have authorized token, you can drop email:
purchases.order_info(order_number="111111111")

# The method also has other params but they're mostly internal:
purchases.order_info(
    order_number=...,
    email=...,
    queries=...,  # Queries that will be included in request, combine any of: ["StatusBannerOrder", "CostsOrder", "ProductListOrder"]. By default, all of them are included.
    # Params below are relevant to ProductListOrder
    skip_products=...,
    skip_product_prices=...,
    take_products=...,
)

💡 Get parsed response with the wrapper:

ikea_api.get_purchase_info(  # Returns parsed purchase object. Items are not listed.
   purchases=purchases,
   order_number=...,
   email=...,
)

🪑 Item info

Get item specification by item code (product number or whatever). There are 2 endpoints to do this because you can't get all the data about all the items using only one endpoint.

ingka_items = ikea_api.IngkaItems(constants)
ingka_items.get_items(["30457903"])

pip_item = ikea_api.PipItem(constants)
pip_item.get_item("30457903")

📦 Item 3D models

Get 3D models by item code.

rotera_item = ikea_api.RoteraItem(constants)
rotera_item.get_item("30221043")

🟢 Item availability

Get availability by item code (product number or whatever).

stock = ikea_api.Stock(constants)
stock.get_stock("30457903")

🔎 Search

Search for products in the product catalog by product name. Optionally also specify a maximum amount of returned search results (defaults to 24) and types of required search results.

search = ikea_api.Search(constants)
search.search("Billy")

# Retrieve 10 search results (default is 24)
search.search("Billy", limit=10)

# Configure search results types
search.search(
    "Billy",
    types=...,  # Combine any of: ["PRODUCT", "CONTENT", "PLANNER", "REFINED_SEARCHES", "ANSWER"]
)

🛠 Utilities

Parse item codes

Parse item codes from string or list.

assert ikea_api.parse_item_codes("111.111.11") == ["11111111"]
assert ikea_api.parse_item_codes("11111111, 222.222.22") == ["11111111", "22222222"]
assert ikea_api.parse_item_codes("111") == []

Format item code

Parse item code and format it.

assert ikea_api.format_item_code("11111111") == "111.111.11"
assert ikea_api.format_item_code("111-111-11") == "111.111.11"
assert ikea_api.format_item_code("111.111.11") == "111.111.11"

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ikea_api-2.4.0.tar.gz (23.4 kB view details)

Uploaded Source

Built Distribution

ikea_api-2.4.0-py3-none-any.whl (30.7 kB view details)

Uploaded Python 3

File details

Details for the file ikea_api-2.4.0.tar.gz.

File metadata

  • Download URL: ikea_api-2.4.0.tar.gz
  • Upload date:
  • Size: 23.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.10.15 Linux/6.8.0-1014-azure

File hashes

Hashes for ikea_api-2.4.0.tar.gz
Algorithm Hash digest
SHA256 3899a930a506994ad56227c3e83be29e1d665eb47cc9f711e68b6575ba5ea42c
MD5 9d76eafd428b94105ae42d237854b293
BLAKE2b-256 6bbc210319afcc82c6678b65a47c4174cb023c06623c6cee742ebdcb80e45d70

See more details on using hashes here.

File details

Details for the file ikea_api-2.4.0-py3-none-any.whl.

File metadata

  • Download URL: ikea_api-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 30.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.8.3 CPython/3.10.15 Linux/6.8.0-1014-azure

File hashes

Hashes for ikea_api-2.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 507dcabfd0f5d167e09bcaad3453270ed716596087bfe94028e1e810ffa808fe
MD5 1b586a27fdcd9d47a909c2206fad51c4
BLAKE2b-256 8e4d7485067a84f5d649a2ef8b3443e86893248c2c356c6c5e13045bf92d59e9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page