Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dax-dot-gay/open-groceries

Scraper for multiple grocery store websites
https://github.com/dax-dot-gay/open-groceries

Last synced: 6 days ago
JSON representation

Scraper for multiple grocery store websites

Host: GitHub
URL: https://github.com/dax-dot-gay/open-groceries
Owner: dax-dot-gay
License: mit
Created: 2023-10-21T19:25:09.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2023-12-05T17:05:21.000Z (12 months ago)
Last Synced: 2024-08-22T18:03:31.255Z (3 months ago)
Language: Python
Homepage:
Size: 179 KB
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # open-groceries

Unified data acquisition across multiple grocery store sites

## Installation

```bash

python3 -m pip install open-groceries

```

## Example Usage

```python

from open_groceries import OpenGrocery

# Initialize adapter clients

client = OpenGrocery()

# Print locations near Times Square

print(client.locations("Times Square NYC"))

# Print search results for "beans"

print(client.search("beans"))

# Print search suggestions for "pot"

print(client.suggest("pot"))

```

## API Documentation

**OpenGrocery:**

The OpenGrocery class is an aggregator for all included adapters. Function/constructor signatures are as follows:

- `OpenGrocery(features = ..., user_agent = ..., adapter_kwargs = ...)`

  - `features`: Optional `str[]`, list of adapter names to initialize.

  - `user_agent`: Optional `str`, user-agent string to pass to APIs.

  - `adapter_kwargs`: Optional `{str: {str: any}}`, mapping of `adapter:{kwargs}` for individual adapter kwargs

- `OpenGrocery().locations(near, include = ...) -> Location[]`: Fetches locations near an address

  - `near`: Required `str`, address to query.

    - Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`

  - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized

  - Returns `Location[]` in order of distance to specified address

- `OpenGrocery().set_nearest_stores(near, include = ...) -> None`: Sets each adapter to its nearest store

  - `near`: Required `str`, address to query.

    - Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`

  - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized

- `OpenGrocery().set_locations(locations) -> None`: Sets each adapter to a specific store

  - `locations`: Required `{str: Location}`, mapping of adapter name to desired location. This function does not check whether the input location is valid for that adapter.

- `OpenGrocery().search(query, include = ...) -> GroceryItem[]`: Searches adapters for a search query

  - `query`: Required `str`, search term to look for

  - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized

  - Returns `GroceryItem[]` in order of similarity to the search term

- `OpenGrocery().adapter(adapter) -> GroceryAdapter | None`: Utility function to return an initialized adapter

  - `adapter`: Required `str`, name of adapter to get

  - Returns specified `GroceryAdapter` if found, or `None` if not

- `OpenGrocery().suggest(term, include = ...) -> str[]`: Gets autocompletion suggestions to search term

  - `term`: Required `str`, search term to suggest for

  - `include`: Optional `str[]`, list of adapters to query. Skips any that aren't initialized

  - Returns `str[]` in order of similarity to search term

**GroceryAdapter:**

The GroceryAdapter class is the abstract parent of all included Adapters. It shoul not be initialized itself, but should instead be subclassed to create Adapters.

- `GroceryAdapter(user_agent = ...)`

  - `user_agent`: Optional `str`, user agent header to send to APIs

- `GroceryAdapter().search_groceries(search) -> GroceryItem[]`: Search for groceries

  - `search`: Required `str`, search term to look for

  - Returns `GroceryItem[]` in the order returned by the website

- `GroceryAdapter().get_grocery_item(id) -> GroceryItem`: Gets a specific grocery item by ID

  - `id`: Required `str`, item ID to return

  - Returns `GroceryItem` returned by the website

- `GroceryAdapter().get_locations(near) -> Location[]`: Gets store locations near an address

  - `near`: Required `str`, address to query.

    - Example formats: `"14620"`, `"Times Square NYC"`, `"Rochester Institute of Technology"`

  - Returns `Location[]` in the order returned by the website

- `GroceryAdapter().set_location(location) -> None`: Sets preferred store location

  - `location`: Required `Location`, location to set

- `GroceryAdapter().suggest(search) -> str[]`: Gets autocomplete suggestions for a search term

  - `term`: Required `str`, search term to suggest for

  - Returns `str[]` in order returned by the website

## Supported Stores

| Store   | Item Search                                 | Item Retrieval                              | Location Search                                   | Location Filtering       | Autocomplete                                      |

| ------- | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------- | ------------------------ | ------------------------------------------------- |

| Wegmans | Full support [Long Term/Versioned API]      | Full support [Long Term/Versioned API]      | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Medium Term/External Versioned API] |

| Costco  | Adequate support [Medium Term/Site Parsing] | Adequate support [Medium Term/Site Parsing] | Full support [Medium Term/External Versioned API] | Full Support [Long Term] | Full support [Long Term/Versioned API]            |