API v1‎ > ‎

Searching

First of all, you need an API Key. The examples shown here do not explain anything related to authentication. Please take a look at the authentication related pages before reporting any problems with the Search API.

The search endpoint is located at http://11870.com/api/v1/search


Search parameters

The available parameters are:

  • q: general text query.
  • as: places located at this area slug.
  • l: string describing the location to perform the search. This location string will be parsed and geocoded by the search service.
  • tag and tagOp: show places with this tag, may be repeated multiple times. Default behaviour is to return places with every tag. tagop can only take the 'or' or 'and' values and modifies multiple tag query behaviour.
  • category and categoryOp: show places belonging to this category. It may be repeated multiple times. Default behaviour is to return places belonging to every category. If the desired behaviour is to obtain places belonging to any category, the categoryOp parameter with a value of 'or' must be used.
  • lat, lon and radius: show places located in the area described by a center point (lat, lon) and the radius specified (in kilometers)
  • bbox: show places located in the bounding box (minLon, minLat, maxLon, maxLat)
  • count: number of elements per page. Value should be under 200, default is 10.
  • page: used to paginate results if more than count are available.
  • sl: location search query. If you want to search a city just add this parameter to the query.
  • scope: search scope. To narrow the query to a user's own sites or even her contacts.

General text query

Text used to query places. Search will be performed using every available data (even data otherwise already specied using other parameters). Examples of these could be: 'romantic dinner in madrid', 'cool pubs', 'museums', etc...


Location

This location string will be parsed and geocoded by the search service, if the geocoding process fails an empty feed will be returned. This method is usually preferred over the area slug query by end users, but results may not be as accurate. Example values for this parameter could be: 'madrid, spain', 'new york', ...


Area Slugs

Area slugs uniquely identify administrative geodivisions. At the moment, there is no way of obtaining  area slugs out of common names like 'Madrid, Spain'. Search results include area slugs (under the *locality and *administrativearea) that may be then used to narrow the search query. Example values for this parameter could be: '/es/madrid', '/us/new-york'.


Tags

You can use the search API to query for places tagged with some specific values. If the parameter tag is specified multiple times, every tag will be taken into account.

If the tagOp parameter is not specified, only places tagged with every value will be returned. If the tagOp parameter is specified with a value of 'or', then results with any of the given tags will be returned.

 

Geo queries

There are two ways of querying for places using geodata: using a center point and a radius or using a bounding box to define the area.

In the first case, the parameters to specify are 'lat', 'lon' and 'radius'. The center point will be given by the tuple (lat, lon) and the area will be determined by the circle of that radius around that point. The radius is specified in kilometers and may contain decimal values. Examples of this kind of query could be: lat=40.0, lon=34.0, radius=0.3; lat=34.2, lon=-23.5, radius=100.

The other kind of query allows to define a square area to perform the search. The bounding box coordinate format is (minLon,minLat,maxLon,maxLat). Examples of this kind of query could be: bbox=-4.209735237779954,41.10093170244638,-1.7902647622200454,42.899068297553626


Category query

11870.com defines a closed set of categories, which is accessible at http://11870.com/api/v1/categories. This kind of query is useful to obtain a list of indian restaurants or two star hotels.

If the categoryOp parameter is not specified, only places categorized with every value will be returned. If the categoryOp parameter is specified with a value of 'or', then results with any of the given categories will be returned.


Location search query

Text used to locate cities. If your query includes this parameter the search results will be cities instead services/places. This query returns results only if we have at least one service/place in that city.

 

Scoping a query 

Under certain circumstances it may be desirable to narrow the search to a user's own places or even her contacts. The scope parameter allows for such kind of queries. Its possible values are: 'global' (default), 'user' and 'contacts'.

For the user site search and contact site search to work, the query should be executed by an application which has been granted at least READ privileges to the users account. That means, for instance, that it is not possible to do this kind of queries using the appToken/authSign authentication method.


Pagination

Resulting places matching a query will be paginated if the number of results exceeds count elements, which is 10 by default. To know if the results are paginated, check for a link with rel='next' inside the feed. First page of results is page number 1.


Search results

Results are returned as an Atom feed with the matching services or places. Every entry follows the 11870 Service/Atom mapping. This Atom feed is annotated with some OpenSearch tags, so expected features like pagination, number of total results, current result set view and so are there.

Please check the OpenSearch specification.


Examples

Searching places with the term 'romantic dinner', with the tags 'cheap' AND 'restaurant'

As mentioned above, this will imply using both the 'q' and 'tag' parameters:

 http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&tag=restaurant

 

Searching places with the term 'romantic dinner', with the tag 'cheap' OR 'restaurant'

This query is exactly equals previous one but it includes the 'tagOp' parameter:

 http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&tag=restaurant&tagOp=or

 

Searching places with the term 'romantic dinner' with the tag 'cheap' and located in Madrid

The last query returned places from all over the world. But we are trying to spend as little money as possible (he's a jerk), so lets narrow our query to our home city:

 http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&as=/es/madrid


How did we get the possible value for the area slug ('as' parameter)? From the results of the first query.

We got 10 results, but there are plenty more:

  http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&as=/es/madrid&page=2

  http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&as=/es/madrid&page=3

 

We could also use the count parameter instead of paginating: 

   http://11870.com/api/v1/search?q=romantic%20dinner&tag=cheap&as=/es/madrid&count=50

 

Searching a city called "Merida" in the word

This query will return all cities that its name includes the world "Merida"

  http://11870.com/api/v1/search?sl=Merida


Comments