Search API Reference

Overview

You can use the Search API to query nextstop for information about places and guides based on a number of criteria. The Search API is subject to the nextstop API Terms of Use and shares the same basic usage model as other nextstop APIs. You should read the API Overview for basic information on registering for an API key and using the nextstop API.

Using the API

To issue a search using the API, you should make a GET request to http://api.nextstop.com/search/. Your request should include all of the required parameters specified below.

API Request

The search API currently supports the following GET parameters.

Required Parameters

• key: A valid nextstop API key for your application. If this request is issued from a browser.
• result_type [guides|places]: Specifies the desired search result type - either matching guides, or individual recommended places.

General Parameters

• callback: The name of your JSONP callback function
• indent: The number of whitespace characters to use when indenting json results. Defaults to none; useful for debugging.
• sort [recent|highest_ranked|most_relevant]: Specifies the desired sort order of results. "highest_ranked" (default) returns the highest quality places or guides as determined by # of likes / recommendations and other proprietary scoring factors. "most_relevant" is only applicable if a q parameter is used, and is the default in this case.
• start: The starting index into the result set to return, defaults to 0.
• num: The maximum number of results to return. Default is 10, current maximum allowed is 50.

Filtering Parameters

• q: A free-text query string. Will match against all text available in the place / guide, but favors higher quality matches and exact title/location matches.
• cat [any|eat-drink|stay-sleep|do-explore|shop-browse]: Restricts results to within one of the comma separated list of categories (i.e., specifying "stay-sleep,eat-drink" will return results that are in either of those two categories).
• keywords: Restricts results to those that include all of the comma separated list of keywords (i.e., specifying "restaurants,chinese" will return results with the keyword restaurants AND chinese).
• profile_id: Restricts results to guides authored by the given profile_id or places recommended by the given profile_id. The profile_id can be found after /profile/[ID] on any profile URL.

Location Limiting Parameters

• loc_ids: Restricts results to within the set of comma separated location ids specified here. You can determine a location id by looking at the URL of any nextstop location page. For example the URL of the San Francisco location page is http://www.nextstop.com/loc/p21IF7pj2yw/san-francisco/ and the location id for san francisco is p21IF7pj2yw.
• loc_name: Restricts results to within the specified location, looked up by name. For example, "San Francisco" or "San Francisco, CA". You will get an error result if the location name was not looked up successfully. Note that while we'll usually do the right thing, there are cases where ambiguous location names (e.g. Portland) may resolve to different locations over time (Portland, Oregon vs. Portland, Maine). You should either provide the most specific location string you can, or use loc_ids to ensure a stable mapping.
• address and rad (must specify both parameters): Restricts results to within rad kilometers of the specified address. Uses Google Maps to geocode address into a lat/lng so any string that works with Google Maps should work here. Returns an error if unable to geocode address.
• lat and lng and rad (must specify all three parameters): Restricts results to within rad kilometers of the specified latitude and longitude.

Note that the lat/lng of a guide is the lat/lng for the area that contains all the places in a guide. For example, if a guide contains places in San Francisco, the lat/lng for the guide will be the center of the city of San Francisco. If the guide contains places in Portland and San Francsico, the lat/lng for the guide will be the center of the United States.

API Response

The search API returns results in the JSON format. Each response includes some core data about the response, and a list of matching places or guides. Take a look at this example response for a places search.

"status": 200,
"message": "", 
"data": {
    "start": 0,
    "resultCount: 1,
    "totalResults": 100, 
    "resultsList": [
        {
            "website": "", 
            "locationName": "San Francisco", 
            "permalink": "http://www.nextstop.com/p/l31u6VYjNv8/dotties-true-blue-cafe/", 
            "name": "Dottie's True Blue Caf\u00e9", 
            "geoAccuracy": "point", 
            "apiEndpoint": "http://api.nextstop.com/p/l31u6VYjNv8/dotties-true-blue-cafe/", 
            "phone": "415/885-2767", 
            "address": "522 Jones St", 
            "lat": 37.786180000000002, 
            "lng": -122.41307399999999, 
            "locationUrl": "http://www.nextstop.com/loc/p21IF7pj2yw/san-francisco/", 
            "recommendationsInfo": {
                "count": 4, 
                "bestRecommendation": {
                    "cardImageUrl": "http://www.nextstop.com/widget/i/minicard/TaL5lLzVICo.png", 
                    "permalink": "http://www.nextstop.com/p/l31u6VYjNv8/dotties-true-blue-cafe/?card=TaL5lLzVICo&", 
                    "name": "Dottie's True Blue Cafe", 
                    "imageAttributionUrl": "http://www.sanfranciscodays.com/photos/large/dotties.jpg", 
                    "authorInfo": {
                        "role": "owner", 
                        "authorName": "donovan", 
                        "authorPhotoUrl": "http://images.nextstop.com/profilepic_-OcsJr5SnRc_nearexpires_80sq", 
                        "authorUrl": "http://www.nextstop.com/profile/donovan/"
                    }, 
                    "smallCachedImageUrl": "http://images.nextstop.com/87ae2ffe-e41e-4616-83b8-ea83f239f73f_150sq", 
                    "largeCachedImageUrl": "http://images.nextstop.com/87ae2ffe-e41e-4616-83b8-ea83f239f73f_300sq", 
                    "dateCreated": "2009-09-15 19:09:00", 
                    "onList": {
                        "apiEndpoint": "http://api.nextstop.com/guide/6eo8vf_Vr8o/san-francisco-neighborhood-gems/", 
                        "permalink": "http://www.nextstop.com/guide/6eo8vf_Vr8o/san-francisco-neighborhood-gems/", 
                        "name": "San Francisco Neighborhood Gems"
                    }, 
                    "imageAttribution": "sanfranciscodays.com", 
                    "shortText": "It could be that any food would seem amazing after waiting in that line - or it could really be that amazing. Actually it probably is.", 
                    "originalImageUrl": "http://www.sanfranciscodays.com/photos/large/dotties.jpg"
                }
            }
        }
    ],
    "resultsInfo": {
        "categoryCounts": {
            "shop-browse": 2, 
            "eat-drink": "100+", 
            "do-explore": 47, 
            "any": 1, 
            "stay-sleep": 2
    }

General API Response Fields

All responses from the nextstop API will include:

• status: 200 if the request succeeded, 500 if failure
• message: A string message, usually giving more details about any errors that occurred.
• data: A container for the data of the response.

Search API Response Fields

• start: The starting index of the search, as specified in the search request
• resultCount: The number of results returned in this search.
• totalResults: The total number matching results for the search. If more than the maximum allowed search results are available, this will be the maximum number of allowed search results (currently 100).
• resultsList: A list of Place Summary Objects or Guide Objects that match the results. See the nextstop API Response Object Reference for details on the format of these objects.
• resultsInfo: Summary information about the results. Currently includes a count of results by category, and by location_id which can be useful for faceting.