yelpapi 2.5.1__tar.gz → 2.7.0__tar.gz

yelpapi-2.7.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - 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
+            exit 1
+          fi
+
+      - name: Extract release notes from CHANGES.md
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '/^## /{if (f) exit; f = (index($0, "## " v " ") == 1); next} f' CHANGES.md > release-notes.md
+          if [ ! -s release-notes.md ]; then
+            echo "No CHANGES.md entry found for ${version}" >&2
+            exit 1
+          fi
+
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - 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

yelpapi-2.7.0/.github/workflows/tests.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  typecheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      # mypy targets python_version in pyproject.toml regardless of the interpreter it runs on, so a single job is
+      # sufficient. Run it on that same minimum version so installed dependencies and stubs match what users on the
+      # minimum get. Keep this equal to python_version.
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Type-check with mypy
+        run: mypy
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

yelpapi-2.7.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+
+# Distribution
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# Tools
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.codebase-memory/
+
+# OS
+.DS_Store

yelpapi-2.7.0/AGENTS.md

@@ -0,0 +1,78 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents working with code in this repository.
+
+## Commands
+
+Install dependencies:
+```
+pip install -e ".[dev]"
+```
+
+Run tests (coverage included by default via `pyproject.toml`):
+```
+pytest
+```
+
+Run a single test:
+```
+pytest tests/test_yelpapi.py::TestYelpAPI::test_calls_api
+```
+
+Type-check (strict; configured in `[tool.mypy]` in `pyproject.toml`, which sets the files to check and targets the minimum supported Python):
+```
+mypy
+```
+
+CI (`.github/workflows/tests.yml`) runs `pytest` on every supported Python version and `mypy` once in a separate `typecheck` job. Both 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__`.
+
+**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.
+
+**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.
+
+## Conventions
+
+- **Typing:** The package ships `py.typed` and must pass strict `mypy`. All library code must be fully annotated. Tests and examples are type-checked but may omit annotations; see the `[[tool.mypy.overrides]]` section of `pyproject.toml`.
+- **Coverage:** Line coverage of `yelpapi/` is 100%. Keep it there; new code paths need tests.
+- **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()`
+  - an entry in the `YelpAPI` class docstring's API list
+  - an entry in the README "METHODS" list
+  - tests covering both validation failures and success
+
+## Supported Python versions
+
+Support only Python versions that are currently maintained (not end-of-life); see https://devguide.python.org/versions/. The minimum is currently 3.11. When adding or dropping a version, update all of these together:
+
+- `requires-python` and the `Programming Language :: Python :: 3.x` classifiers in `pyproject.toml`
+- `python_version` in `[tool.mypy]` in `pyproject.toml` (keep it equal to the minimum)
+- the `test` job's matrix in `.github/workflows/tests.yml`
+- the Python version used by the `typecheck` job in `tests.yml` (keep it equal to the minimum, matching `python_version`)
+- the Python version used by `publish.yml` (use the newest supported version)
+- the "REQUIREMENTS" section of `README.md`
+- `CHANGES.md`
+
+Once the minimum is raised, newly available language and typing features (e.g., `typing.Self` with 3.11) may be used.
+
+## Releasing
+
+1. Bump `version` in `pyproject.toml`.
+2. Add a `## X.Y.Z (YYYY-MM-DD)` entry at the top of `CHANGES.md`.
+3. Commit, push, and make sure CI is green. The publish workflow does not run tests.
+4. Push an annotated tag:
+
+   ```
+   git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
+   ```
+
+Pushing a `v*` tag triggers `.github/workflows/publish.yml`. Before publishing, it fails if the tag doesn't match the `pyproject.toml` version, or if `CHANGES.md` has no entry for that version. It then builds, publishes to PyPI, and creates a GitHub release whose notes are that version's `CHANGES.md` entry.

yelpapi-2.7.0/CHANGES.md

@@ -0,0 +1,85 @@
+# Changes
+
+## 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.
+* Declared `__all__` in the `yelpapi` package so `from yelpapi import YelpAPI` passes `mypy --strict` (no implicit re-export) and Pyright's private-import checks.
+* Added the `Typing :: Typed` classifier.
+* A JSON response body that isn't an object (e.g., a string or list) now raises `YelpAPI.YelpAPIError` instead of an unhelpful `TypeError` or silently returning the wrong type.
+
+## 2.6.0 (2026-03-17)
+* Added 5 new API endpoints: Business Engagement Metrics (`business_engagement_query`), Business Service Offerings (`business_service_offerings_query`), Categories (`categories_query`), Category by Alias (`category_query`), and Review Highlights (`review_highlights_query`).
+* Updated all documentation URLs to the current `docs.developer.yelp.com` reference format.
+* Migrated from `setup.py` to `pyproject.toml` (hatchling build backend).
+* Dropped Python 3.8 support; added Python 3.13 and 3.14. Minimum supported version is now 3.9.
+* Migrated CI from Travis CI to GitHub Actions.
+* Added type hints throughout.
+* Reached 100% test coverage.
+
+## 2.5.1 (2023-10-10)
+* Raise [`HTTPError`](https://requests.readthedocs.io/en/latest/api/#requests.HTTPError) if one occurs (PR #25).
+
+## 2.5.0 (2022-08-04)
+* Implemented new `close()` method to close the `requests.Session` object we use for performant API interactions. This can also be used as a context manager (this is the preferred way).
+    * Clarified [`README.md`](README.md) to make it clear that the user should always be sure to close the connection.
+
+## 2.4.1 (2022-08-01)
+* Dropping EOL Python versions, adding newly-supported versions.
+* Updating dependencies in [`requirements.txt`](requirements.txt).
+* Updating project URL (moved from [@gfairchild](https://github.com/gfairchild)'s personal namespace to [@lanl](https://github.com/lanl)'s namespace).
+
+## 2.4.0 (2019-04-19)
+* `match_type` parameter for the business match endpoint was deprecated on April 1, 2019 (see [Yelp's changelog](https://www.yelp.com/developers/v3/changelog)). (courtesy @davebulaval)
+* Added a check to ensure a required parameter, `address1`, is provided when using the business match endpoint. (courtesy @davebulaval)
+* Support for Python versions <3.4 is removed (i.e., this no longer works with Python 2.7). This is due to some dependencies that also have abandoned Python 2 support.
+
+## 2.3.0 (2018-07-11)
+* Provided a means to set timeouts to API calls. (courtesy @goodspark)
+* Added unit tests, including Travis CI automation. (courtesy @goodspark)
+
+## 2.2.2 (2018-01-28)
+* Add better top-level documentation for `YelpAPI`.
+* To avoid wasting API calls on obviously invalid requests, consistently check for parameters required for requests to succeed.
+
+## 2.2.1 (2018-01-28)
+* Fix a few minor inconsistencies in the code.
+
+## 2.2.0 (2018-01-28)
+* Revised to remove token/secret access and instead use API keys. Yelp will move to API keys only in March 2018. (courtesy @tamos)
+* An API key is now needed to instantiate a `YelpAPI` object. (courtesy @tamos)
+* Added support for 3 new endpoints:
+    * [Event Lookup API](https://www.yelp.com/developers/documentation/v3/event)
+    * [Event Search API](https://www.yelp.com/developers/documentation/v3/event_search)
+    * [Featured Event API](https://www.yelp.com/developers/documentation/v3/featured_event)
+* `business_match_query` no longer assumes the country is the U.S. if the country code is missing.
+
+## 2.1.0 (2017-10-19)
+* Implement new [Business Match API](https://www.yelp.com/developers/documentation/v3/business_match).   
+**NOTE**: This API is currently in beta. Yelp requires your app join the [Yelp Developer Beta Program](https://www.yelp.com/developers/v3/manage_app) to gain access to it.
+
+## 2.0.1 (2017-02-27)
+* Remove reliance on `ez_setup.py`.
+* Add `setup.cfg` to instruct the build process to build universal wheels.
+
+## 2.0 (2017-02-27)
+* Implement the new Yelp Fusion API (aka Yelp v3 API). Note that yelpapi v1.4 is the last version to support the Yelp v2 API. [The Yelp v2 API is being deprecated, so all new developers should move to the new Fusion API ASAP.](https://engineeringblog.yelp.com/2017/02/recent-improvements-to-the-fusion-api.html)
+    * Use OAuth 2.0 for authentication.
+    * Implement new [Transaction Search API](https://www.yelp.com/developers/documentation/v3/transactions_search), [Reviews API](https://www.yelp.com/developers/documentation/v3/business_reviews), and [Autocomplete API](https://www.yelp.com/developers/documentation/v3/autocomplete).
+
+## 1.4 (2016-05-10)
+* Use HTTPS for all API calls.
+* Use new string formatter.
+* Remove `YelpError` since the business API now returns a JSON error when given a bad business ID.
+
+## 1.3 (2015-05-22)
+* Adding support for the [Phone Search API](https://www.yelp.com/developers/documentation/v2/phone_search).
+
+## 1.2 (2013-10-08)
+* yelpapi is now fully Python 3+ compliant.
+
+## 1.1 (2013-10-04)
+* Transitioning from using [python-oauth2](https://github.com/simplegeo/python-oauth2) and [requests](https://github.com/kennethreitz/requests) to just using [requests-oauthlib](https://github.com/requests/requests-oauthlib).
+* Moving to setuptools (using [ez_setup.py](https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py) to manage it).
+
+## 1.0 (2013-10-03)
+* Initial release.

yelpapi-2.7.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: yelpapi
+Version: 2.7.0
+Summary: yelpapi is a pure Python implementation of the Yelp Fusion API.
+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>
+License: Copyright (c) 2013, Triad National Security, LLC
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+        following conditions are met:
+        
+        * Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+          disclaimer.
+        * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+          following disclaimer in the documentation and/or other materials provided with the distribution.
+        * Neither the name of Triad National Security, LLC nor the names of its contributors may be used to endorse or
+          promote products derived from this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+        INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+        THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: AUTHORS.md
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: faker; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: requests-mock; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yelpapi
+
+[![Tests](https://github.com/lanl/yelpapi/actions/workflows/tests.yml/badge.svg)](https://github.com/lanl/yelpapi/actions/workflows/tests.yml)
+
+## LICENSE
+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.
+
+## REQUIREMENTS
+This code requires Python 3.11 or higher and [requests](https://github.com/psf/requests).
+
+## INSTALL
+yelpapi is available on PyPI at https://pypi.org/project/yelpapi/.
+
+Install using [pip](https://pip.pypa.io/):
+
+    pip install yelpapi
+
+## USING THIS CODE
+This API is demonstrated more thoroughly in [examples.py](examples/examples.py), but the following chunk of code demonstrates basic use of yelpapi:
+
+```python
+from yelpapi import YelpAPI
+with YelpAPI(api_key) as yelp_api:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+```
+
+You can also set timeouts so API calls do not block indefinitely in degraded network conditions:
+
+```python
+from yelpapi import YelpAPI
+with YelpAPI(api_key, timeout_s=3.0) as yelp_api:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+```
+
+Under the covers, this module uses a [`requests.Session`](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects) object for issuing all API calls, which offers potentially significant performance benefits over issuing separate API calls outside of a session. You should be sure to close the underlying session when all API interactions are complete. The above examples demonstrate using the class as a context manager, which will automatically close the connection when you're done and is the preferred way of using the class, but you can also manually close it like this if a context manager won't work for your use case:
+
+```python
+from yelpapi import YelpAPI
+yelp_api = YelpAPI(api_key)
+try:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+finally:
+    yelp_api.close()
+```
+
+## METHODS
+* [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 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(...)`
+* [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(...)`
+* [Phone Search API](https://docs.developer.yelp.com/reference/v3_business_phone_search) - `phone_search_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(...)`

yelpapi-2.7.0/README.md

@@ -0,0 +1,64 @@
+# yelpapi
+
+[![Tests](https://github.com/lanl/yelpapi/actions/workflows/tests.yml/badge.svg)](https://github.com/lanl/yelpapi/actions/workflows/tests.yml)
+
+## LICENSE
+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.
+
+## REQUIREMENTS
+This code requires Python 3.11 or higher and [requests](https://github.com/psf/requests).
+
+## INSTALL
+yelpapi is available on PyPI at https://pypi.org/project/yelpapi/.
+
+Install using [pip](https://pip.pypa.io/):
+
+    pip install yelpapi
+
+## USING THIS CODE
+This API is demonstrated more thoroughly in [examples.py](examples/examples.py), but the following chunk of code demonstrates basic use of yelpapi:
+
+```python
+from yelpapi import YelpAPI
+with YelpAPI(api_key) as yelp_api:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+```
+
+You can also set timeouts so API calls do not block indefinitely in degraded network conditions:
+
+```python
+from yelpapi import YelpAPI
+with YelpAPI(api_key, timeout_s=3.0) as yelp_api:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+```
+
+Under the covers, this module uses a [`requests.Session`](https://requests.readthedocs.io/en/latest/user/advanced/#session-objects) object for issuing all API calls, which offers potentially significant performance benefits over issuing separate API calls outside of a session. You should be sure to close the underlying session when all API interactions are complete. The above examples demonstrate using the class as a context manager, which will automatically close the connection when you're done and is the preferred way of using the class, but you can also manually close it like this if a context manager won't work for your use case:
+
+```python
+from yelpapi import YelpAPI
+yelp_api = YelpAPI(api_key)
+try:
+    search_results = yelp_api.search_query(term='ice cream', location='austin, tx')
+finally:
+    yelp_api.close()
+```
+
+## METHODS
+* [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 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(...)`
+* [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(...)`
+* [Phone Search API](https://docs.developer.yelp.com/reference/v3_business_phone_search) - `phone_search_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(...)`

yelpapi-2.7.0/examples/examples.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python
+
+"""
+    Copyright (c) 2013, Triad National Security, LLC
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+    following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+      disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+      following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the name of Triad National Security, LLC nor the names of its contributors may be used to endorse or
+      promote products derived from this software without specific prior written permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+    DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+    SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+    WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+# Example call:
+#     ./examples.py "[API Key]"
+
+import argparse
+from pprint import pprint
+
+from yelpapi import YelpAPI
+
+SEP = '\n-------------------------------------------------------------------------\n'
+
+argparser = argparse.ArgumentParser(
+    description='Example Yelp queries using yelpapi. '
+                'Visit https://docs.developer.yelp.com/docs/fusion-intro to get the necessary API keys.',
+)
+argparser.add_argument('api_key', type=str, help='Yelp Fusion API Key')
+args = argparser.parse_args()
+
+with YelpAPI(args.api_key) as yelp_api:
+    # Search API: https://docs.developer.yelp.com/reference/v3_business_search
+    print("***** 5 best rated ice cream places in Austin, TX *****\nyelp_api.search_query(term='ice cream', location='austin, tx', sort_by='rating', limit=5)\n")
+    response = yelp_api.search_query(term='ice cream', location='austin, tx', sort_by='rating', limit=5)
+    pprint(response)
+    print(SEP)
+
+    # Search API (by coordinates): https://docs.developer.yelp.com/reference/v3_business_search
+    # all Yelp categories: https://docs.developer.yelp.com/docs/resources-categories
+    # centroid: https://www.flickr.com/places/info/2487956
+    print("***** 5 bike rentals in San Francisco *****\nyelp_api.search_query(categories='bikerentals', longitude=-122.4392, latitude=37.7474, limit=5)\n")
+    response = yelp_api.search_query(categories='bikerentals', longitude=-122.4392, latitude=37.7474, limit=5)
+    pprint(response)
+    print(SEP)
+
+    # Phone Search API: https://docs.developer.yelp.com/reference/v3_business_phone_search
+    print("***** search for business by phone number *****\nyelp_api.phone_search_query(phone='+13193375512')\n")
+    response = yelp_api.phone_search_query(phone='+13193375512')
+    pprint(response)
+    print(SEP)
+
+    # Business Match API: https://docs.developer.yelp.com/reference/v3_business_match
+    print("***** search for business match *****\nyelp_api.business_match_query(name='Splash Cafe', address1='197 Pomeroy Ave', city='Pismo Beach', state='CA', country='US')\n")
+    response = yelp_api.business_match_query(
+        name='Splash Cafe',
+        address1='197 Pomeroy Ave',
+        city='Pismo Beach',
+        state='CA',
+        country='US',
+    )
+    pprint(response)
+    print(SEP)
+
+    # Transaction Search API: https://docs.developer.yelp.com/reference/v3_transaction_search
+    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)
+    print(SEP)
+
+    # Business API: https://docs.developer.yelp.com/reference/v3_business_info
+    print("***** business information for Amy's on 6th St. *****\nyelp_api.business_query(id='amys-ice-creams-austin-3')\n")
+    response = yelp_api.business_query(id='amys-ice-creams-austin-3')
+    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")
+    response = yelp_api.autocomplete_query(text='Hambur', longitude=-91.5327, latitude=41.6560)
+    pprint(response)
+    print(SEP)
+
+    # Categories API: https://docs.developer.yelp.com/reference/v3_all_categories
+    print("***** all Yelp categories *****\nyelp_api.categories_query()\n")
+    response = yelp_api.categories_query()
+    pprint(response)
+    print(SEP)
+
+    # Category API: https://docs.developer.yelp.com/reference/v3_categories
+    print("***** details for the 'icecream' category *****\nyelp_api.category_query(alias='icecream')\n")
+    response = yelp_api.category_query(alias='icecream')
+    pprint(response)
+    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()
+    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)
+
+    # 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")
+    response = yelp_api.featured_event_query(location='New York City, NY')
+    pprint(response)
+    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
+    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)
+    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
+    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)
+    print(SEP)
+
+    # 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)
+    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)