Skip to content

Commit

Permalink
Merge pull request #69 from Yelp/dan98765-patch-1
Browse files Browse the repository at this point in the history 
Update README APIv2 -> APIv3 (Fusion)
  • Loading branch information
@dan98765
dan98765 committed Jul 27, 2018
2 parents ecf3aa0 + d233302 commit a035769
Showing 1 changed file with 11 additions and 143 deletions.
154 changes: 11 additions & 143 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,10 @@

# yelp-python

A Python library for the Yelp API. It simplifies the process of authentication, request construction, and response parsing for Python developers using the Yelp API. This clientlib is built and tested on Python 2.7 and 3.6.
A Python library for the [Yelp Fusion API](https://www.yelp.com/developers/documentation/v3/get_started). It simplifies the process of request construction, and response parsing for Python developers. This clientlib is built and tested on Python 2.7 and 3.6.

# Deprecated
This library works only with the older Yelp API V2.
Please file issues on this repository for bugs/feature requests for this python client. For bugs/features requests for the Yelp Fusion API itself, please open issues on the [dedicated Yelp Fusion repository](https://github.com/Yelp/yelp-fusion).

Starting on April 1st, 2017, you will no longer be able to sign up for API v2.

Please use the newer Yelp Fusion API instead:
* https://www.yelp.com/developers/documentation/v3/get_started
* https://github.com/Yelp/yelp-fusion

## Installation

Expand All @@ -24,131 +18,31 @@ Install yelp-python from PyPI using:

### Basics

The library uses a client object to query against the API. Make a client by creating an instance of `Oauth1Authenticator` with your API key and passing that to the client constructor. You can sign up for an API key at [https://www.yelp.com/developers/manage_api_keys](https://www.yelp.com/developers/manage_api_keys).
You must have a Yelp Fusion API key to make requests to the API. Sign up for an API key at https://www.yelp.com/developers/v3/manage_app. Instantiate `yelp.client.Client` with your API key, and start making requests!

```
from yelp.client import Client
from yelp.oauth1_authenticator import Oauth1Authenticator
auth = Oauth1Authenticator(
consumer_key=YOUR_CONSUMER_KEY,
consumer_secret=YOUR_CONSUMER_SECRET,
token=YOUR_TOKEN,
token_secret=YOUR_TOKEN_SECRET
)
MY_API_KEY = "abcefghijklmnopqrstuvqwxy123456789" # Replace this with your real API key
client = Client(auth)
```

To keep your API access keys secure, we highly recommend putting them in a file which you add to `.gitignore`. For example, store your keys in a file called `config_secret.json`.

```
{
"consumer_key": "YOUR_CONSUMER_KEY",
"consumer_secret": "YOUR_CONSUMER_SECRET",
"token": "YOUR_TOKEN",
"token_secret": "YOUR_TOKEN_SECRET"
}
```

Then load it into your code to construct a client.

```
# read API keys
with io.open('config_secret.json') as cred:
creds = json.load(cred)
auth = Oauth1Authenticator(**creds)
client = Client(auth)
client = Client(MY_API_KEY)
```

Now you can use the client object to make requests.

### Search API

There are three ways to query the Search API: `search`, `search_by_bounding_box`, and `search_by_coordinates`. For each of these methods, additional parameters are optional. The full list of parameters can be found on the [Search API Documentation](https://www.yelp.com/developers/documentation/v2/search_api).

```
params = {
'term': 'food',
'lang': 'fr'
}
client.search('San Francisco', **params)
```

`search_by_bounding_box` takes a southwest latitude/longitude and a northeast latitude/longitude as the location boundary ([details](https://www.yelp.com/developers/documentation/v2/search_api#searchGBB)).

```
client.search_by_bounding_box(
37.900000,
-122.500000,
37.788022,
-122.399797,
**params
)
```

`search_by_coordinates` takes a geographic coordinate ([details](https://www.yelp.com/developers/documentation/v2/search_api#searchGC)).

client.search_by_coordinates(37.788022, -122.399797, **params)

### Business API

To query the Business API use the `get_business` function with a business id. You can also pass in locale parameters as specified in the [Business API Documentation](https://www.yelp.com/developers/documentation/v2/business).

```
params = {
'lang': 'fr'
}
client.get_business('yelp-san-francisco', **params)
```
### Business Details Endpoint

### Phone Search API
Endpoint documentation: https://www.yelp.com/developers/documentation/v3/business

To query the Phone Search API use the `phone_search` function with a phone number. Additional parameters can be found on [Phone Search API Documentation](https://www.yelp.com/developers/documentation/v2/phone_search).
To query the Business Details Endpoint use the `get_business` function with a Yelp business alias (i.e. `yelp-san-francisco`) or ID (i.e. `4kMBvIEWPxWkWKFN__8SxQ`). You can also pass in the locale parameter as specified in the [Business Details Endpoint Documentation](https://www.yelp.com/developers/documentation/v3/business).

```
params = {
'category': 'fashion'
}
> business_response = client.get_business('yelp-san-francisco')
client.phone_search('+15555555555', **params)
> business_response
Business(alias='yelp-san-francisco', attributes=None, categories=[Category(alias='massmedia', title='Mass Media')], coordinates=Coordinates(latitude=37.7867703362929, longitude=-122.399958372115), display_phone='(415) 908-3801', hours=[Hours(hours_type='REGULAR', is_open_now=True, open=[DayHours(day=0, end='1800', is_overnight=False, start='0800'), DayHours(day=1, end='1800', is_overnight=False, start='0800'), DayHours(day=2, end='1800', is_overnight=False, start='0800'), DayHours(day=3, end='1800', is_overnight=False, start='0800'), DayHours(day=4, end='1800', is_overnight=False, start='0800')])], id='4kMBvIEWPxWkWKFN__8SxQ', image_url='https://s3-media2.fl.yelpcdn.com/bphoto/nQK-6_vZMt5n88zsAS94ew/o.jpg', is_claimed=True, is_closed=False, location=Location(address1='140 New Montgomery St', address2='', address3='', city='San Francisco', country='US', cross_streets='Natoma St & Minna St', display_address=['140 New Montgomery St', 'San Francisco, CA 94105'], state='CA', zip_code='94105'), name='Yelp', phone='+14159083801', photos=['https://s3-media2.fl.yelpcdn.com/bphoto/nQK-6_vZMt5n88zsAS94ew/o.jpg', 'https://s3-media2.fl.yelpcdn.com/bphoto/yFHIb9gob4TzhKUemMOPww/o.jpg', 'https://s3-media1.fl.yelpcdn.com/bphoto/EHCfkEpZraIfPl8gvCo1tg/o.jpg'], rating=2.0, review_count=8421, transactions=[], url='https://www.yelp.com/biz/yelp-san-francisco?adjust_creative=wpr6gw4FnptTrk1CeT8POg&utm_campaign=yelp_api_v3&utm_medium=api_v3_business_lookup&utm_source=wpr6gw4FnptTrk1CeT8POg')
```

## Responses

Responses from the API are parsed into Python objects.

Search and phone search responses are parsed into `SearchResponse` objects.

```
>>> response = client.search('San Francisco')
>>> response.businesses
[<Business 1>, <Business 2>, ...]
>>> response.businesses[0].name
u'The Flying Falafel'
>>> response.businesses[0].rating
4.5
```

Business responses are parsed into `BusinessResponse` objects.

```
>>> response = client.get_business('yelp-san-francisco')
>>> response.business.name
u'Yelp'
>>> response.business.categories
[Category(name=u'Local Flavor', alias=u'localflavor'), Category(name=u'Mass Media', alias=u'massmedia')]
```

For a full list of available response fields, take a look at the [documentation](https://www.yelp.com/developers/documentation/v2/overview) or the classes defined in `yelp/obj`.

## Contributing

1. Fork it (http://github.com/yelp/yelp-python/fork)
Expand All @@ -166,29 +60,3 @@ $ . venv-yelp/bin/activate
### Testing

Please write tests for any new features. We use pytest + tox so just run `tox` to run the full test suite. Full py.test documentation [here](http://pytest.org/latest/contents.html).

If you are adding a new integration test, you will need to connect to the Yelp API. You can set this up by creating a file `tests/json/credentials_secret.json` that contains your API keys in the following format:

```
{
"consumer_key": "YOUR_CONSUMER_KEY",
"consumer_secret": "YOUR_CONSUMER_SECRET",
"token": "YOUR_TOKEN",
"token_secret": "YOUR_TOKEN_SECRET"
}
```

We use VCR.py to record and serialize HTTP requests. Add your test to `tests/integration_test.py` and use the decorator

@int_vcr.use_cassette(**cassette_params)

The first time you run the test, VCR.py will record the HTTP request to the folder `/tests/integration/vcr_cassettes` in a yaml file of the same name as the test, filtering out your oauth tokens prior to writing. VCR.py will replay the response for subsequent runs. This allows us to have deterministic tests and continuously integrate with Travis CI. To clear the recorded response, delete the cassette file. Running the test again will make a new HTTP request and record it. For more information, see [VCR.py documentation](https://github.com/kevin1024/vcrpy).

### Git Workflow

We are using the [git flow](http://nvie.com/posts/a-successful-git-branching-model/)
workflow. Atlassian has a [solid overview](https://www.atlassian.com/git/workflows#!workflow-gitflow).
Essentially, new development is merged into the develop branch from feature
branches, then merged from develop to a release branch, then to master from
the release branch. Master should always contain the most recently released
version of the library.

0 comments on commit a035769

Please sign in to comment.