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
The search endpoint is located at http://11870.com/api/v1/search
The available parameters are:
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...
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 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'.
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.
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
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.
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.
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.
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.
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.
As mentioned above, this will imply using both the 'q' and 'tag' parameters:
This query is exactly equals previous one but it includes the 'tagOp' parameter:
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:
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:
We could also use the count parameter instead of paginating:
This query will return all cities that its name includes the world "Merida"