yelpapi 2.7.0__tar.gz → 2.8.0__tar.gz

{yelpapi-2.7.0 → yelpapi-2.8.0}/.github/workflows/publish.yml

@@ -16,15 +16,16 @@ jobs:
     steps:
       - uses: actions/checkout@v7
 
-      - uses: actions/setup-python@v7
+      - name: Set up Python
+        uses: actions/setup-python@v7
         with:
           python-version: '3.15'
 
       - name: Verify tag matches package version
         run: |
           version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
-          if [ "v${version}" != "${{ github.ref_name }}" ]; then
-            echo "Tag ${{ github.ref_name }} does not match pyproject.toml version ${version}" >&2
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${version}" >&2
             exit 1
           fi
 
@@ -48,4 +49,4 @@ jobs:
       - name: Create GitHub release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: gh release create "${{ github.ref_name }}" dist/* --title "YelpAPI ${{ github.ref_name }}" --notes-file release-notes.md
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --title "YelpAPI ${GITHUB_REF_NAME}" --notes-file release-notes.md

{yelpapi-2.7.0 → yelpapi-2.8.0}/.github/workflows/tests.yml

@@ -2,12 +2,36 @@ name: Tests
 
 on:
   push:
+    branches: [master]
   pull_request:
 
 permissions:
   contents: read
 
+# Cancel an in-progress run when a newer commit is pushed to the same branch or pull request.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # Ruff targets requires-python in pyproject.toml regardless of the interpreter it runs on.
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.x'
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint with ruff
+        run: ruff check --output-format=github
+
   typecheck:
     runs-on: ubuntu-latest
 
@@ -31,6 +55,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
 

{yelpapi-2.7.0 → yelpapi-2.8.0}/AGENTS.md

@@ -24,19 +24,24 @@ Type-check (strict; configured in `[tool.mypy]` in `pyproject.toml`, which sets
 mypy
 ```
 
-CI (`.github/workflows/tests.yml`) runs `pytest` on every supported Python version and `mypy` once in a separate `typecheck` job. Both must pass.
+Lint (configured in `[tool.ruff]` in `pyproject.toml`; `ruff check --fix` applies safe fixes):
+```
+ruff check
+```
+
+CI (`.github/workflows/tests.yml`) runs `pytest` on every supported Python version, plus `mypy` and `ruff check` once each in separate `typecheck` and `lint` jobs. All must pass.
 
 ## Architecture
 
-This is a thin Python wrapper around the [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro). The entire implementation lives in `yelpapi/yelpapi.py` as a single `YelpAPI` class, re-exported from `yelpapi/__init__.py` via `__all__`.
+This is a thin Python wrapper around Yelp's public REST APIs: the [Yelp Places API](https://docs.developer.yelp.com/docs/places-intro), the [Yelp AI API](https://docs.developer.yelp.com/docs/yelp-ai-api), [Yelp Insights](https://docs.developer.yelp.com/docs/yelp-insights), and the [Home Services API](https://docs.developer.yelp.com/docs/home-services-api). The entire implementation lives in `yelpapi/yelpapi.py` as a single `YelpAPI` class, re-exported from `yelpapi/__init__.py` via `__all__`.
 
 **Design philosophy:** The wrapper is intentionally minimal and extensible — all API parameters are passed through `**kwargs` directly to the HTTP request, so it doesn't break when Yelp adds new parameters. The only thing that would break it is a URL scheme change. Public methods return `dict[str, Any]`; don't introduce `TypedDict`s or response models, since they would break this pass-through design.
 
-**Request flow:** Each public method (e.g., `search_query`, `business_query`) validates required parameters, then delegates to `_query()`, which strips `None`-valued kwargs before issuing the GET request via a shared `requests.Session`. `_query()` raises `requests.HTTPError` for HTTP error statuses, and raises `YelpAPI.YelpAPIError` if the JSON body isn't an object or contains an `error` key. Methods that require a location share a `_require_location_or_lat_lng()` helper.
+**Request flow:** Each public method (e.g., `search_query`, `business_query`) validates required parameters, then delegates to `_get()` (GET; kwargs become query string parameters) or `_post()` (POST; kwargs become the JSON body). Both strip `None`-valued kwargs before issuing the request via a shared `requests.Session`, then hand the response to `_parse_response()`, which raises `requests.HTTPError` for HTTP error statuses, returns `{}` for empty `202`/`204` responses, and raises `YelpAPI.YelpAPIError` if the JSON body isn't an object or contains an `error` key. Methods that require a location share a `_require_location_or_lat_lng()` helper.
 
 **Session management:** A single `requests.Session` is reused for all calls (performance benefit). Users should close it via context manager (`with YelpAPI(...) as api`) or explicitly via `api.close()`.
 
-**Tests** use `requests-mock` (via the `mock_request` autouse fixture in `conftest.py`) to intercept HTTP calls, and `Faker` for generating random test data. No real API calls are made in tests.
+**Tests** use `requests-mock` (via the `mock_request` autouse fixture in `conftest.py`) to intercept HTTP calls, and a fixed-seed `Faker` for generating test data, so every run is deterministic. No real API calls are made in tests.
 
 ## Conventions
 
@@ -45,7 +50,8 @@ This is a thin Python wrapper around the [Yelp Fusion API](https://docs.develope
 - **Style:** Use single quotes for strings, and 120-character lines.
 - **Adding an endpoint** requires all of the following:
   - a `*_API_URL` constant
-  - a method that validates required parameters and calls `_query()`
+  - a method that validates required parameters and calls `_get()` (GET) or `_post()` (POST); path parameters are positional arguments inserted with `quote(value, safe='')`
+  - an entry in the `GET_ENDPOINTS` or `POST_ENDPOINTS` table in `tests/test_yelpapi.py` (use `PATH_PARAM` for path parameters)
   - an entry in the `YelpAPI` class docstring's API list
   - an entry in the README "METHODS" list
   - tests covering both validation failures and success

{yelpapi-2.7.0 → yelpapi-2.8.0}/CHANGES.md

@@ -1,5 +1,23 @@
 # Changes
 
+## 2.8.0 (2026-10-28)
+* **Heads up for subclassers:** the private request helper `YelpAPI._query()` has been renamed to `YelpAPI._get()`, and the new POST helper is `YelpAPI._post()`.
+    * If your subclass *calls* `self._query(...)` to reach endpoints this library doesn't wrap, switch to `self._get(...)`. `_query()` still works for this release but emits a `FutureWarning`.
+    * If your subclass *overrides* `_query()` (e.g., for caching, retries, or logging), override `_get()` (and `_post()` for POST endpoints) instead. Public methods no longer call `_query()`, so an override of it is no longer used. Defining such a subclass emits a `FutureWarning`.
+    * `_query()` will be removed in 2.9.0.
+* Added 8 new API endpoints: AI Chat (`ai_chat_query`), Business Insights (`business_insights_query`), Business Food & Drinks Insights (`business_food_and_drinks_insights_query`), Business Risk Signal Insights (`business_risk_signals_insights_query`), Business Request a Phone Call (`business_rapc_enabledness_query`), Jobs (`jobs_query`), Job Survey (`job_survey_query`), and Request a Quote (`request_a_quote_query`).
+* Added support for POST endpoints, which send `**kwargs` as the JSON request body (with `None` values removed). Successful responses with no body (e.g., `202 Accepted`) return an empty dict.
+* `business_service_offerings_query` now emits a `DeprecationWarning`, because Yelp has deprecated the endpoint in favor of "Jobs offered" on the Business API.
+* Fixed: a latitude or longitude of `0` (the equator or prime meridian) is now accepted by `search_query`, `featured_event_query`, and `transaction_search_query` instead of raising `ValueError`.
+* Fixed: `business_match_query` now accepts an empty `address1`, which Yelp allows for service businesses with no street address.
+* Fixed: a malformed `error` object in a response (e.g., a plain string, or one missing `code` or `description`) now raises `YelpAPI.YelpAPIError` instead of a `TypeError` or `KeyError`.
+* Path parameters (business IDs, aliases, event IDs, job aliases, and transaction types) are now percent-encoded, so characters like `/`, `?`, and `#` can no longer change the URL that is requested.
+* Clarified the `YelpAPI.YelpAPIError` docs: HTTP error statuses raise `requests.HTTPError`, while `YelpAPIError` covers error objects and non-object bodies in successful responses.
+* Updated docstrings to match Yelp's current docs (plan and access requirements, `match_threshold`, the 20-ID limit for `business_ids`, and required fields for Request a Quote).
+* Fixed the examples so they catch `requests.HTTPError` and keep going when an endpoint needs a paid plan or extra access.
+* Strengthened the test suite: every endpoint's URL, HTTP method, and parameters are now checked, and test data is deterministic.
+* Added [Ruff](https://docs.astral.sh/ruff/) linting, run in CI.
+
 ## 2.7.0 (2026-10-28)
 * Dropped support for end-of-life Python 3.9 and 3.10; added Python 3.15. Minimum supported version is now 3.11.
 * `YelpAPI.__enter__` now returns `Self`, so subclasses are typed correctly when used as context managers.

{yelpapi-2.7.0 → yelpapi-2.8.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: yelpapi
-Version: 2.7.0
-Summary: yelpapi is a pure Python implementation of the Yelp Fusion API.
+Version: 2.8.0
+Summary: yelpapi is a pure Python implementation of Yelp's public REST APIs (Places, AI, Insights, and Home Services).
 Project-URL: Homepage, https://github.com/lanl/yelpapi
 Project-URL: Changelog, https://github.com/lanl/yelpapi/blob/master/CHANGES.md
 Author-email: Geoffrey Fairchild <mail@gfairchild.com>
@@ -49,6 +49,7 @@ Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: requests-mock; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: types-requests; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -60,7 +61,7 @@ Description-Content-Type: text/markdown
 This software is licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause). Please refer to the separate [LICENSE](LICENSE) file for the exact text of the license. You are obligated to give attribution if you use this code.
 
 ## ABOUT
-yelpapi is a pure Python implementation of the [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro). It is simple, fast, and robust to any changes Yelp may make to the API in the future.
+yelpapi is a pure Python implementation of Yelp's public REST APIs, including the [Yelp Places API](https://docs.developer.yelp.com/docs/places-intro), the [Yelp AI API](https://docs.developer.yelp.com/docs/yelp-ai-api), [Yelp Insights](https://docs.developer.yelp.com/docs/yelp-insights), and the [Home Services API](https://docs.developer.yelp.com/docs/home-services-api). It is simple, fast, and robust to any changes Yelp may make to its APIs in the future.
 
 ## REQUIREMENTS
 This code requires Python 3.11 or higher and [requests](https://github.com/psf/requests).
@@ -101,18 +102,28 @@ finally:
 ```
 
 ## METHODS
+* [AI Chat API](https://docs.developer.yelp.com/reference/v2_ai_chat) - `ai_chat_query(...)`
 * [Autocomplete API](https://docs.developer.yelp.com/reference/v3_autocomplete) - `autocomplete_query(...)`
 * [Business API](https://docs.developer.yelp.com/reference/v3_business_info) - `business_query(...)`
 * [Business Engagement Metrics API](https://docs.developer.yelp.com/reference/v3_get_businesses_engagement) - `business_engagement_query(...)`
+* [Business Food & Drinks Insights API](https://docs.developer.yelp.com/reference/v3_get_business_food_and_drinks_insights) - `business_food_and_drinks_insights_query(...)`
+* [Business Insights API](https://docs.developer.yelp.com/reference/v3_businesses_insights) - `business_insights_query(...)`
 * [Business Match API](https://docs.developer.yelp.com/reference/v3_business_match) - `business_match_query(...)`
-* [Business Service Offerings API](https://docs.developer.yelp.com/reference/v3_business_service_offerings) - `business_service_offerings_query(...)`
+* [Business Request a Phone Call API](https://docs.developer.yelp.com/reference/v3_business_rapc_enabledness) - `business_rapc_enabledness_query(...)`
+* [Business Risk Signal Insights API](https://docs.developer.yelp.com/reference/v3_get_business_risk_signals_insights) - `business_risk_signals_insights_query(...)`
+* [Business Service Offerings API](https://docs.developer.yelp.com/reference/v3_business_service_offerings) - `business_service_offerings_query(...)` (deprecated by Yelp in favor of "Jobs offered" on the Business API)
 * [Categories API](https://docs.developer.yelp.com/reference/v3_all_categories) - `categories_query(...)`
 * [Category API](https://docs.developer.yelp.com/reference/v3_categories) - `category_query(...)`
 * [Event Lookup API](https://docs.developer.yelp.com/reference/v3_event) - `event_lookup_query(...)`
 * [Event Search API](https://docs.developer.yelp.com/reference/v3_events_search) - `event_search_query(...)`
 * [Featured Event API](https://docs.developer.yelp.com/reference/v3_featured_event) - `featured_event_query(...)`
+* [Job Survey API](https://docs.developer.yelp.com/reference/v3_job_survey) - `job_survey_query(...)`
+* [Jobs API](https://docs.developer.yelp.com/reference/v3_get_jobs) - `jobs_query(...)`
 * [Phone Search API](https://docs.developer.yelp.com/reference/v3_business_phone_search) - `phone_search_query(...)`
+* [Request a Quote API](https://docs.developer.yelp.com/reference/v3_raq_submit_project) - `request_a_quote_query(...)`
 * [Review Highlights API](https://docs.developer.yelp.com/reference/v3_business_review_highlights) - `review_highlights_query(...)`
 * [Reviews API](https://docs.developer.yelp.com/reference/v3_business_reviews) - `reviews_query(...)`
 * [Search API](https://docs.developer.yelp.com/reference/v3_business_search) - `search_query(...)`
 * [Transaction Search API](https://docs.developer.yelp.com/reference/v3_transaction_search) - `transaction_search_query(...)`
+
+Yelp's [GraphQL API](https://docs.developer.yelp.com/docs/graphql-intro) is not wrapped, since it uses GraphQL queries rather than REST parameters.

{yelpapi-2.7.0 → yelpapi-2.8.0}/README.md

@@ -6,7 +6,7 @@
 This software is licensed under the [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause). Please refer to the separate [LICENSE](LICENSE) file for the exact text of the license. You are obligated to give attribution if you use this code.
 
 ## ABOUT
-yelpapi is a pure Python implementation of the [Yelp Fusion API](https://docs.developer.yelp.com/docs/fusion-intro). It is simple, fast, and robust to any changes Yelp may make to the API in the future.
+yelpapi is a pure Python implementation of Yelp's public REST APIs, including the [Yelp Places API](https://docs.developer.yelp.com/docs/places-intro), the [Yelp AI API](https://docs.developer.yelp.com/docs/yelp-ai-api), [Yelp Insights](https://docs.developer.yelp.com/docs/yelp-insights), and the [Home Services API](https://docs.developer.yelp.com/docs/home-services-api). It is simple, fast, and robust to any changes Yelp may make to its APIs in the future.
 
 ## REQUIREMENTS
 This code requires Python 3.11 or higher and [requests](https://github.com/psf/requests).
@@ -47,18 +47,28 @@ finally:
 ```
 
 ## METHODS
+* [AI Chat API](https://docs.developer.yelp.com/reference/v2_ai_chat) - `ai_chat_query(...)`
 * [Autocomplete API](https://docs.developer.yelp.com/reference/v3_autocomplete) - `autocomplete_query(...)`
 * [Business API](https://docs.developer.yelp.com/reference/v3_business_info) - `business_query(...)`
 * [Business Engagement Metrics API](https://docs.developer.yelp.com/reference/v3_get_businesses_engagement) - `business_engagement_query(...)`
+* [Business Food & Drinks Insights API](https://docs.developer.yelp.com/reference/v3_get_business_food_and_drinks_insights) - `business_food_and_drinks_insights_query(...)`
+* [Business Insights API](https://docs.developer.yelp.com/reference/v3_businesses_insights) - `business_insights_query(...)`
 * [Business Match API](https://docs.developer.yelp.com/reference/v3_business_match) - `business_match_query(...)`
-* [Business Service Offerings API](https://docs.developer.yelp.com/reference/v3_business_service_offerings) - `business_service_offerings_query(...)`
+* [Business Request a Phone Call API](https://docs.developer.yelp.com/reference/v3_business_rapc_enabledness) - `business_rapc_enabledness_query(...)`
+* [Business Risk Signal Insights API](https://docs.developer.yelp.com/reference/v3_get_business_risk_signals_insights) - `business_risk_signals_insights_query(...)`
+* [Business Service Offerings API](https://docs.developer.yelp.com/reference/v3_business_service_offerings) - `business_service_offerings_query(...)` (deprecated by Yelp in favor of "Jobs offered" on the Business API)
 * [Categories API](https://docs.developer.yelp.com/reference/v3_all_categories) - `categories_query(...)`
 * [Category API](https://docs.developer.yelp.com/reference/v3_categories) - `category_query(...)`
 * [Event Lookup API](https://docs.developer.yelp.com/reference/v3_event) - `event_lookup_query(...)`
 * [Event Search API](https://docs.developer.yelp.com/reference/v3_events_search) - `event_search_query(...)`
 * [Featured Event API](https://docs.developer.yelp.com/reference/v3_featured_event) - `featured_event_query(...)`
+* [Job Survey API](https://docs.developer.yelp.com/reference/v3_job_survey) - `job_survey_query(...)`
+* [Jobs API](https://docs.developer.yelp.com/reference/v3_get_jobs) - `jobs_query(...)`
 * [Phone Search API](https://docs.developer.yelp.com/reference/v3_business_phone_search) - `phone_search_query(...)`
+* [Request a Quote API](https://docs.developer.yelp.com/reference/v3_raq_submit_project) - `request_a_quote_query(...)`
 * [Review Highlights API](https://docs.developer.yelp.com/reference/v3_business_review_highlights) - `review_highlights_query(...)`
 * [Reviews API](https://docs.developer.yelp.com/reference/v3_business_reviews) - `reviews_query(...)`
 * [Search API](https://docs.developer.yelp.com/reference/v3_business_search) - `search_query(...)`
 * [Transaction Search API](https://docs.developer.yelp.com/reference/v3_transaction_search) - `transaction_search_query(...)`
+
+Yelp's [GraphQL API](https://docs.developer.yelp.com/docs/graphql-intro) is not wrapped, since it uses GraphQL queries rather than REST parameters.

{yelpapi-2.7.0 → yelpapi-2.8.0}/examples/examples.py

@@ -25,19 +25,47 @@
 
 # Example call:
 #     ./examples.py "[API Key]"
+#
+# Some endpoints below require a paid plan or access that must be requested from Yelp. Those calls are made via
+# run_restricted(), which prints the HTTP error and moves on instead of aborting the script.
 
 import argparse
+import contextlib
+from collections.abc import Callable
 from pprint import pprint
+from typing import Any
+
+import requests
 
 from yelpapi import YelpAPI
 
 SEP = '\n-------------------------------------------------------------------------\n'
 
+
+def print_http_error(e: requests.HTTPError) -> None:
+    """Print an HTTP error, including Yelp's error object if the response has one."""
+    print(e)
+    if e.response is not None:
+        with contextlib.suppress(ValueError):
+            print(e.response.json().get('error'))
+
+
+def run_restricted(call: Callable[[], dict[str, Any]]) -> dict[str, Any] | None:
+    """Run a call that may fail for API keys without the required plan or access."""
+    try:
+        response = call()
+    except requests.HTTPError as e:
+        print('(this endpoint may require a paid plan or extra access for your API key)')
+        print_http_error(e)
+        return None
+    pprint(response)
+    return response
+
 argparser = argparse.ArgumentParser(
     description='Example Yelp queries using yelpapi. '
-                'Visit https://docs.developer.yelp.com/docs/fusion-intro to get the necessary API keys.',
+                'Visit https://docs.developer.yelp.com/docs/places-intro to get the necessary API keys.',
 )
-argparser.add_argument('api_key', type=str, help='Yelp Fusion API Key')
+argparser.add_argument('api_key', type=str, help='Yelp API key')
 args = argparser.parse_args()
 
 with YelpAPI(args.api_key) as yelp_api:
@@ -74,6 +102,7 @@ with YelpAPI(args.api_key) as yelp_api:
     print(SEP)
 
     # Transaction Search API: https://docs.developer.yelp.com/reference/v3_transaction_search
+    # NOTE: 'delivery' is the only supported transaction type, and only US locations are supported
     print("***** businesses in Dallas supporting delivery transactions *****\nyelp_api.transaction_search_query(transaction_type='delivery', location='dallas, tx')\n")
     response = yelp_api.transaction_search_query(transaction_type='delivery', location='dallas, tx')
     pprint(response)
@@ -85,19 +114,6 @@ with YelpAPI(args.api_key) as yelp_api:
     pprint(response)
     print(SEP)
 
-    # Reviews API: https://docs.developer.yelp.com/reference/v3_business_reviews
-    print("***** selected reviews for Amy's on 6th St. *****\nyelp_api.reviews_query(id='amys-ice-creams-austin-3')\n")
-    response = yelp_api.reviews_query(id='amys-ice-creams-austin-3')
-    pprint(response)
-    print(SEP)
-
-    # Review Highlights API: https://docs.developer.yelp.com/reference/v3_business_review_highlights
-    # NOTE: requires a Premium Plan
-    print("***** review highlights for Amy's on 6th St. *****\nyelp_api.review_highlights_query(id='amys-ice-creams-austin-3')\n")
-    response = yelp_api.review_highlights_query(id='amys-ice-creams-austin-3')
-    pprint(response)
-    print(SEP)
-
     # Autocomplete API: https://docs.developer.yelp.com/reference/v3_autocomplete
     # centroid: https://www.flickr.com/places/info/2427422
     print("***** autocomplete results for 'Hambur' in Iowa City *****\nyelp_api.autocomplete_query(text='Hambur', longitude=-91.5327, latitude=41.6560)\n")
@@ -106,7 +122,7 @@ with YelpAPI(args.api_key) as yelp_api:
     print(SEP)
 
     # Categories API: https://docs.developer.yelp.com/reference/v3_all_categories
-    print("***** all Yelp categories *****\nyelp_api.categories_query()\n")
+    print('***** all Yelp categories *****\nyelp_api.categories_query()\n')
     response = yelp_api.categories_query()
     pprint(response)
     print(SEP)
@@ -118,16 +134,17 @@ with YelpAPI(args.api_key) as yelp_api:
     print(SEP)
 
     # Event Search API: https://docs.developer.yelp.com/reference/v3_events_search
-    print("***** event search result *****\nyelp_api.event_search_query()\n")
-    response = yelp_api.event_search_query()
+    print("***** event search result for New York City, NY *****\nyelp_api.event_search_query(location='New York City, NY')\n")
+    response = yelp_api.event_search_query(location='New York City, NY')
     pprint(response)
     print(SEP)
 
     # Event Lookup API: https://docs.developer.yelp.com/reference/v3_event
-    print("***** event lookup result using previous search's first event *****\nyelp_api.event_lookup_query(id=response['events'][0]['id'])\n")
-    response = yelp_api.event_lookup_query(id=response['events'][0]['id'])
-    pprint(response)
-    print(SEP)
+    if response.get('events'):
+        print("***** event lookup result using previous search's first event *****\nyelp_api.event_lookup_query(id=response['events'][0]['id'])\n")
+        response = yelp_api.event_lookup_query(id=response['events'][0]['id'])
+        pprint(response)
+        print(SEP)
 
     # Featured Event API: https://docs.developer.yelp.com/reference/v3_featured_event
     print("***** featured event lookup result for New York City, NY *****\nyelp_api.featured_event_query(location='New York City, NY')\n")
@@ -135,32 +152,91 @@ with YelpAPI(args.api_key) as yelp_api:
     pprint(response)
     print(SEP)
 
+    # AI Chat API: https://docs.developer.yelp.com/reference/v2_ai_chat
+    print("***** AI chat about ice cream in Austin, TX *****\nyelp_api.ai_chat_query(query='Where can I get great ice cream in Austin, TX?')\n")
+    run_restricted(lambda: yelp_api.ai_chat_query(query='Where can I get great ice cream in Austin, TX?'))
+    print(SEP)
+
+    # ----- The endpoints below require a paid plan or extra access. -----
+
+    # Reviews API: https://docs.developer.yelp.com/reference/v3_business_reviews
+    # NOTE: requires an Enhanced or Premium Plan
+    print("***** selected reviews for Amy's on 6th St. *****\nyelp_api.reviews_query(id='amys-ice-creams-austin-3')\n")
+    run_restricted(lambda: yelp_api.reviews_query(id='amys-ice-creams-austin-3'))
+    print(SEP)
+
+    # Review Highlights API: https://docs.developer.yelp.com/reference/v3_business_review_highlights
+    # NOTE: requires a Premium Plan
+    print("***** review highlights for Amy's on 6th St. *****\nyelp_api.review_highlights_query(id='amys-ice-creams-austin-3')\n")
+    run_restricted(lambda: yelp_api.review_highlights_query(id='amys-ice-creams-austin-3'))
+    print(SEP)
+
     # Business Engagement Metrics API: https://docs.developer.yelp.com/reference/v3_get_businesses_engagement
-    # NOTE: requires special permissions on the Yelp Places API key
+    # NOTE: part of Yelp Insights; requires Yelp Insights access for your API key
     print("***** engagement metrics for Amy's on 6th St. *****\nyelp_api.business_engagement_query(business_ids='amys-ice-creams-austin-3')\n")
-    response = yelp_api.business_engagement_query(business_ids='amys-ice-creams-austin-3')
-    pprint(response)
+    run_restricted(lambda: yelp_api.business_engagement_query(business_ids='amys-ice-creams-austin-3'))
     print(SEP)
 
     # Business Service Offerings API: https://docs.developer.yelp.com/reference/v3_business_service_offerings
-    # NOTE: requires special permissions on the Yelp Places API key
+    # NOTE: requires special permissions on the Yelp API key
+    # DEPRECATED: Yelp recommends "Jobs offered" on the Business API instead
     print("***** service offerings for Amy's on 6th St. *****\nyelp_api.business_service_offerings_query(id='amys-ice-creams-austin-3')\n")
-    response = yelp_api.business_service_offerings_query(id='amys-ice-creams-austin-3')
-    pprint(response)
+    run_restricted(lambda: yelp_api.business_service_offerings_query(id='amys-ice-creams-austin-3'))
+    print(SEP)
+
+    # Business Insights API: https://docs.developer.yelp.com/reference/v3_businesses_insights
+    # NOTE: part of Yelp Insights; requires Yelp Insights access for your API key
+    # date_range_start/date_range_end are months in YYYYMM format
+    print("***** business insights for Amy's on 6th St. *****\nyelp_api.business_insights_query(business_ids='amys-ice-creams-austin-3', date_range_start='202601', date_range_end='202603')\n")
+    run_restricted(lambda: yelp_api.business_insights_query(
+        business_ids='amys-ice-creams-austin-3',
+        date_range_start='202601',
+        date_range_end='202603',
+    ))
     print(SEP)
 
+    # Business Food & Drinks Insights API: https://docs.developer.yelp.com/reference/v3_get_business_food_and_drinks_insights
+    # NOTE: part of Yelp Insights; requires Yelp Insights access for your API key
+    print("***** food & drinks insights for Amy's on 6th St. *****\nyelp_api.business_food_and_drinks_insights_query(id='amys-ice-creams-austin-3')\n")
+    run_restricted(lambda: yelp_api.business_food_and_drinks_insights_query(id='amys-ice-creams-austin-3'))
+    print(SEP)
+
+    # Business Risk Signal Insights API: https://docs.developer.yelp.com/reference/v3_get_business_risk_signals_insights
+    # NOTE: part of Yelp Insights; requires Yelp Insights access for your API key
+    print("***** risk signal insights for Amy's on 6th St. *****\nyelp_api.business_risk_signals_insights_query(id='amys-ice-creams-austin-3')\n")
+    run_restricted(lambda: yelp_api.business_risk_signals_insights_query(id='amys-ice-creams-austin-3'))
+    print(SEP)
+
+    # Jobs API: https://docs.developer.yelp.com/reference/v3_get_jobs
+    # NOTE: part of the Home Services API; access is disabled by default and must be requested from Yelp
+    print("***** home service jobs matching a leaky faucet *****\nyelp_api.jobs_query(query='I need someone to fix a leaky faucet')\n")
+    jobs = run_restricted(lambda: yelp_api.jobs_query(query='I need someone to fix a leaky faucet'))
+    print(SEP)
+
+    # Job Survey API: https://docs.developer.yelp.com/reference/v3_job_survey
+    # NOTE: part of the Home Services API; access is disabled by default and must be requested from Yelp
+    if jobs and jobs.get('jobs'):
+        job_alias = jobs['jobs'][0]['job_alias']
+        print(f"***** survey for the best-matching job from the previous query *****\nyelp_api.job_survey_query(job_alias='{job_alias}')\n")
+        run_restricted(lambda: yelp_api.job_survey_query(job_alias=job_alias))
+        print(SEP)
+
+    # ----- Error handling -----
+    # HTTP error statuses (e.g., 400 for bad parameters, 404 for unknown IDs) raise requests.HTTPError.
+    # YelpAPI.YelpAPIError is raised when a successful HTTP response contains a Yelp error object or isn't a JSON object.
+
     # Example erroneous search query
     print("***** sample erroneous search query *****\nyelp_api.search_query(term='ice cream', location='austin, tx', sort_by='BAD_SORT')\n")
     try:
         # sort can only take on values "best_match", "rating", "review_count", or "distance"
         yelp_api.search_query(term='ice cream', location='austin, tx', sort_by='BAD_SORT')
-    except YelpAPI.YelpAPIError as e:
-        print(e)
+    except requests.HTTPError as e:
+        print_http_error(e)
     print(SEP)
 
     # Example erroneous business query
     print("***** sample erroneous business query *****\nyelp_api.business_query(id='fake-business')\n")
     try:
         yelp_api.business_query(id='fake-business')
-    except YelpAPI.YelpAPIError as e:
-        print(e)
+    except requests.HTTPError as e:
+        print_http_error(e)

{yelpapi-2.7.0 → yelpapi-2.8.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yelpapi"
-version = "2.7.0"
-description = "yelpapi is a pure Python implementation of the Yelp Fusion API."
+version = "2.8.0"
+description = "yelpapi is a pure Python implementation of Yelp's public REST APIs (Places, AI, Insights, and Home Services)."
 readme = "README.md"
 license = {file = "LICENSE"}
 authors = [
@@ -39,6 +39,7 @@ dev = [
     "pytest",
     "pytest-cov",
     "requests-mock",
+    "ruff",
     "types-requests",
 ]
 
@@ -49,6 +50,29 @@ Changelog = "https://github.com/lanl/yelpapi/blob/master/CHANGES.md"
 [tool.pytest.ini_options]
 addopts = "-vl --cov=yelpapi --import-mode=importlib"
 
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+    "Q",    # flake8-quotes
+    "RUF",  # ruff-specific rules
+]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+
+[tool.ruff.lint.per-file-ignores]
+# The examples print each call verbatim on one line.
+"examples/*" = ["E501"]
+
 [tool.mypy]
 strict = true
 python_version = "3.11"

yelpapi-2.8.0/release-notes.md

@@ -0,0 +1,17 @@
+* **Heads up for subclassers:** the private request helper `YelpAPI._query()` has been renamed to `YelpAPI._get()`, and the new POST helper is `YelpAPI._post()`.
+    * If your subclass *calls* `self._query(...)` to reach endpoints this library doesn't wrap, switch to `self._get(...)`. `_query()` still works for this release but emits a `FutureWarning`.
+    * If your subclass *overrides* `_query()` (e.g., for caching, retries, or logging), override `_get()` (and `_post()` for POST endpoints) instead. Public methods no longer call `_query()`, so an override of it is no longer used. Defining such a subclass emits a `FutureWarning`.
+    * `_query()` will be removed in 2.9.0.
+* Added 8 new API endpoints: AI Chat (`ai_chat_query`), Business Insights (`business_insights_query`), Business Food & Drinks Insights (`business_food_and_drinks_insights_query`), Business Risk Signal Insights (`business_risk_signals_insights_query`), Business Request a Phone Call (`business_rapc_enabledness_query`), Jobs (`jobs_query`), Job Survey (`job_survey_query`), and Request a Quote (`request_a_quote_query`).
+* Added support for POST endpoints, which send `**kwargs` as the JSON request body (with `None` values removed). Successful responses with no body (e.g., `202 Accepted`) return an empty dict.
+* `business_service_offerings_query` now emits a `DeprecationWarning`, because Yelp has deprecated the endpoint in favor of "Jobs offered" on the Business API.
+* Fixed: a latitude or longitude of `0` (the equator or prime meridian) is now accepted by `search_query`, `featured_event_query`, and `transaction_search_query` instead of raising `ValueError`.
+* Fixed: `business_match_query` now accepts an empty `address1`, which Yelp allows for service businesses with no street address.
+* Fixed: a malformed `error` object in a response (e.g., a plain string, or one missing `code` or `description`) now raises `YelpAPI.YelpAPIError` instead of a `TypeError` or `KeyError`.
+* Path parameters (business IDs, aliases, event IDs, job aliases, and transaction types) are now percent-encoded, so characters like `/`, `?`, and `#` can no longer change the URL that is requested.
+* Clarified the `YelpAPI.YelpAPIError` docs: HTTP error statuses raise `requests.HTTPError`, while `YelpAPIError` covers error objects and non-object bodies in successful responses.
+* Updated docstrings to match Yelp's current docs (plan and access requirements, `match_threshold`, the 20-ID limit for `business_ids`, and required fields for Request a Quote).
+* Fixed the examples so they catch `requests.HTTPError` and keep going when an endpoint needs a paid plan or extra access.
+* Strengthened the test suite: every endpoint's URL, HTTP method, and parameters are now checked, and test data is deterministic.
+* Added [Ruff](https://docs.astral.sh/ruff/) linting, run in CI.
+

{yelpapi-2.7.0 → yelpapi-2.8.0}/tests/conftest.py

@@ -11,4 +11,7 @@ def mock_request():
 
 @pytest.fixture
 def faker():
-    return Faker()
+    # Seeded so that every run uses the same data.
+    fake = Faker()
+    fake.seed_instance(0)
+    return fake