Places (Search)


https://api.apontador.com.br/v2/places

Method: GET

Authorization: You can use your access_token from application or from user

Parameters:

  • wt: json(default) or xml, the API accepts this information in the request's header(i.e. "Accept: application/xml" or "Accept: application/json"). So you can use the parameter wt or use Accept header.
  • q: this is the term you are searching(your first filter)
  • fq: (optional) specify filters based in some fields. For more than one filter you can either use several fq parameters or use the operator AND (in upper case)
  • fl: (optional) specify the fields that will be returned for each result
  • sort: (optional) the default is relevance, you can choose distance or name desc
  • rows: (optional) the default is 10 and maximum 50
  • start: (optional) the default is 0, it's used for pagination
  • location.lat: (optional) decimal degree latitude, used to search around a location and together with location.lng
  • location.lng: (optional) decimal degree longitude, used to search around a location and together with location.lat
  • location.nw.lat: (optional) decimal degree latitude from top left rectangle, used to search in a bounding box
  • location.nw.lng: (optional) decimal degree longitude from top left rectangle, used to search in a bounding box
  • location.se.lat: (optional) decimal degree latitude from bottom right rectangle, used to search in a bounding box
  • location.se.lng: (optional) decimal degree longitude from bottom right rectangle, used to search in a bounding box
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria

If successful, this call will return:

{
      "results":{
	  "header":{
	        "found":15801,
	        "rows":1,
	        "start":0,
	        "next":"https://api.apontador.com.br/v2/places/?q=pizzaria&rows=1&start=1"},
	        "places":[{
                  "id":"C4088149120E2O0E2C",
                  "link":{
                              "rel":"self",
                              "uri":"https://api.apontador.com.br/v2/places/C4088149120E2O0E2C"
                         },
                  "name":"Siriji Restaurante e Pizzaria",
                  "phones":[
                              "558130323740"
                           ],
                  "urlApontador":"http://www.apontador.com.br/local/pe/recife/restaurantes/C4088149120E2O0E2C/siriji_restaurante_e_pizzaria.html",
                  "address":{
                              "country":"BR",
                              "state":"PE",
                              "city":"Recife",
                              "street":"Estrada de Belêm",
                              "number":"671",
                              "zipcode":"52030000"
                            },
                  "location":{
                              "lat":"-8.0339",
                              "lng":"-34.88604"
                             },
                  "categories":[
                                 {
                                      "id":"67",
                                      "name":"RESTAURANTES",
                                      "link":{
                                                "rel":"self",
                                                "uri":"https://api.apontador.com.br/v2/categories/67"
                                              },
                                      "subcategory":{
                                                       "id":"95264",
                                                       "name":"Pizzerias"
                                                     }     
                                 },
                               ],
                  "statistics":{
                                 "pageviews":"158",
                                 "rating":"4.0",
                                 "reviews":"2",
                                 "checkins":"0",
                                 "photos":"3"
                                }
	                  }]
	   }
}
		

Below you can find different cases of search

1. Filtering by region

The request from our initial search can be filtered using parameter fq.

Find pizzaria in city Sao Paulo
https://api.apontador.com.br/v2/places/?q=pizzaria&fq=address.city:"sao paulo"&wt=json
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria&fq=address.city:"sao paulo"
Find pizzaria in city Sao Paulo and district Mooca
https://api.apontador.com.br/v2/places/?q=pizzaria&fq=address.city:"sao paulo" AND address.district:mooca&wt=json
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria&fq=address.city:"sao paulo" AND address.district:mooca 

2. Nearby Search

Find pizzaria around Estádio do Juventus (lat:-23.57361,lng:-46.58861), in Mooca, sorted by distance.
https://api.apontador.com.br/v2/places/?q=pizzaria&location.lat=-23.57361&location.lng=-46.58861&sort=location.distance&wt=json
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria&location.lat=-23.57361&location.lng=-46.58861&sort=location.distance 
Find pizzaria in bounding box defined by map extents(latitude and longitude in southest, latitude and longitude in northwest)
https://api.apontador.com.br/v2/places/?q=pizzaria&location.nw.lat=-23.57036&location.nw.lng=-46.59420&location.se.lat=-23.57660&location.se.lng=-46.58410&sort=location.distance&wt=json
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria&location.nw.lat=-23.57036&location.nw.lng=-46.59420&location.se.lat=-23.57660&location.se.lng=-46.58410&sort=location.distance 

3. Filtering fields in the response using fl parameter

Find pizzaria around Estádio do Juventus (lat:-23.57361,lng:-46.58861), in Mooca, sorted by distance. The response just contains id, name, phones, statistics.rating
https://api.apontador.com.br/v2/places/?q=pizzaria&location.lat=-23.57361&location.lng=-46.58861&sort=location.distance&fl=name,phones,statistics.rating&wt=json
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?q=pizzaria&location.lat=-23.57361&location.lng=-46.58861&sort=location.distance&fl=name,phones,statistics.rating 

4. Filtering results by category

Find Top 5 restaurants in subcategory pizzaria in city Sao Paulo
https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.name:pizzarias&fq=address.city:"sao paulo"&wt=json&rows=5&sort=statistics.rating desc,statistics.pageviews desc
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.name:pizzarias&fq=address.city:"sao paulo"&rows=5&sort=statistics.rating desc,statistics.pageviews desc 
Find by category_Id in city Sao Paulo
https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.id:67&fq=address.city:"sao paulo"&wt=json&rows=5&sort=statistics.rating desc,statistics.pageviews desc
				
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.id:67&fq=address.city:"sao paulo"&rows=5&sort=statistics.rating desc,statistics.pageviews desc 
				
Find by subcategory_Id in city Sao Paulo
https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.id:78&fq=address.city:"sao paulo"&wt=json&rows=5&sort=statistics.rating desc,statistics.pageviews desc
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?fq=categories.category.subcategory.id:78&fq=address.city:"sao paulo"&rows=5&sort=statistics.rating desc,statistics.pageviews desc 

5. Filtering by list

Find places in specific list
https://api.apontador.com.br/v2/places/?fq=placeLists.placeList.id:71
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?fq=placeLists.placeList.id:71

6. Filtering by utility

Find places with specific utility (book a table, hotel reservation, etc)
Food Delivery - utilities.utility.name:\"Pedir Delivery\" Book a Table - utilities.utility.name:\"Reservar Mesa\" Hotel Reservation - utilities.utility.name:\"Reservar Hotel\" Deals Offer - utilities.utility.name:\"Ver Ofertas\"
https://api.apontador.com.br/v2/places/?fq=utilities.utility.name:\"Ver Ofertas\" AND featured.photo.medium:[* TO *]&wt=json&fl=categories.category.name,id,name,address.state,address.city,address.street,address.number,location.lat,location.lng,statistics.reviews,statistics.rating,featured.photo.medium,utilities.utility.id,utilities.utility.name 
curl -X GET -H "Accept: application/json" -H "Authorization: Bearer ACCESS_TOKEN" https://api.apontador.com.br/v2/places/?fq=utilities.utility.name:\"Ver Ofertas\" AND featured.photo.medium:[* TO *]&wt=json&fl=categories.category.name,id,name,address.state,address.city,address.street,address.number,location.lat,location.lng,statistics.reviews,statistics.rating,featured.photo.medium,utilities.utility.id,utilities.utility.name