Discover

Discover Place

You can discover places for the specified category. The Discover Place features can be used as presented below:

Request URI

Request URI	Supported Methods
/v5/discover/place/json	POST

POST

The EntityDiscoverPlaceRequest object allows customizing the request.

DiscoverPlaceOptions lite_result property, DiscoverPlaceFilters ev_filter and geo_filter properties provide ability to customize search results.

Lite Result - When it's set to true, the only basic POI attributes are returned. This provides support for returning up to 1000 results.

- entity id
- entity type
- place
    - name
    - categories[]
    - address[]
        - geo_coordinates
- facets
    - ev_connectors  // only ev_connector facet will be returned in response with limited EV attributes
        - total_connector
        - connector_counts
        - connectors[]
            - connector_type
            - power_feed_level
            - charger_brand
            - connector_number
            - available
            - max_power
            - is_free

Polygon filter - Constrains the discover results to any polygon shape.
Bounding box filter - Constrains the discover results to a rectangular bounding box.
Radius filter - Constrains the discover results to a circle of a specified radius.
Electric vehicle charge station search - Specialized search service for electric vehicle charge stations.

Request Body

Name	Data Type	Required/Optional	Description
requestParam	EntityDiscoverPlaceRequest	required	Request object to customize the request.

Request Example

{
  "locale": "en-US",
  "location": {
    "latitude": 37.78509,
    "longitude": -122.41988
  },
  "limit": 2,
  "discover_options": {
    "lite_result": true,
    "sort_type": "DISTANCE"
  },
  "categories": [
    "771"
  ],
  "filters": {
    "geo_filter": {
      "type": "BBOX",
      "bbox": {
        "bottom_left": {
          "latitude": 37.70908,
          "longitude": -122.50249
        },
        "top_right": {
          "latitude": 37.7897,
          "longitude": -122.39108
        }
      }
    },
    "ev_filter": {
      "connector_types": [
        "30001",
        "30007"
      ],
      "power_feed_levels": [
        2
      ],
      "charger_brands": [
        "99100001"
      ],
      "free_charge": true
    }
  }
}

Response Body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	Status	required	Status
response_time	Number	required	Response time in milliseconds.
reference_id	String	required	Reference id associated with response.
results	[ Entity ]	required	List of results that match search criteria.

Response Example

{
  "status":{
    "status":12200,
    "message":"SUCCESS"
  },
  "reference_id":"f60dcf2c-c925-481b-b2c9-00a1fdd5b08f",
  "results":[
    {
      "id":"P-YP-NYL88GEENUh5UJhIicEPBA",
      "type":"PLACE",
      "place":{
        "name":"Noe Cafe",
        "categories":[
          {
            "id":"241",
            "name":"Coffee Houses"
          }
        ],
        "address":{
          "geo_coordinates":{
            "latitude":37.74851,
            "longitude":-122.42922
          }
        }
      }
    },
    {
      "id":"P-YP-MweAq9W5Vza9XdhO6j-z-w",
      "type":"PLACE",
      "place":{
        "name":"Four Barrel Coffee",
        "categories":[
          {
            "id":"241",
            "name":"Coffee Houses"
          }
        ],
        "address":{
          "geo_coordinates":{
            "latitude":37.72903,
            "longitude":-122.4038
          }
        }
      }
    }
  ],
  "response_time":71
}

Status Code

Code	Message	Description
12200	SUCCESS	Indicates that no errors occurred.
12400	INVALID_REQUEST	Indicates either that a required parameter is missing or value of a parameter cannot be parsed.
12500	INTERNAL_SERVER_ERROR	Indicates technical difficulties on API.

Discover Brand

The discover brand feature enables discovery of brands around a specific location. Powerful discovery experiences can be built enabling the end user to discover popular brands around a provided location.

Request URI

Request URI	Supported Methods
/v5/discover/brand/json	GET, POST

GET

Use optional category parameter with an applicable category id to limit the returned brands belonging to the specific category. For example, if the use case is for restaurant brands then set the category to restaurants.

Request Parameters

Name	Description	Required
location	Geo-coordinate of the user location (latitude and longitude separated by ",").	Yes
category	Category id	No
limit	Number of results in response. Default value: 10	No
locale	The preferred language for the response content.	No
user_id	The id associated with the user who is sending the request.	No

Request Example

{host}/entity/v5/discover/brand/json?locale=en-US&location=37.12419%2C-121.98828&category=241&limit=5

POST

The EntityDiscoverBrandRequest object allows customizing the request to narrow down results. Use optional category property with an applicable category id to limit the returned brands belonging to the specific category. For example, if the use case is for restaurant brands then set the category to restaurants.

Request Body

Name	Data Type	Required/Optional	Description
requestParam	EntityDiscoverBrandRequest	required	Request object to customize the request.

Request Example

{
  "category": "241",
  "location": {
    "latitude": 37.78509,
    "longitude": -122.41988
  },
  "filters": {
    "geo_filter": {
      "type": "radius",
      "radius_in_meter": 2000
    }
  },
  "limit": 5
}

Response Body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	Status	required	Status
response_time	Number	required	Response time in milliseconds.
reference_id	String	required	Reference id associated with response.
results	[ Brand ]	required	List of results that match search criteria.

Response Example

{
  "status":{
    "code":12200,
    "message":"SUCCESS"
  },
  "response_time":26,
  "reference_id":"dd4d502c-1441-44ff-b59e-356b597fa449",
  "results":[
    {
      "brand_id":"5e322758adf911e2913340182e32cb0b",
      "brand_name":"peet's coffee & tea"
    },
    {
      "brand_id":"67aebb66adf911e2930e1c642a71fbdd",
      "brand_name":"nordstorm"
    }
  ]
}

Status Code

Code	Message	Description
12200	SUCCESS	Indicates that no errors occurred.
12400	INVALID_REQUEST	Indicates either that a required parameter is missing or value of a parameter cannot be parsed.
12500	INTERNAL_SERVER_ERROR	Indicates technical difficulties on API.

Discover Category

The discover category feature enables discovery of categories around a specific location. Developers can build powerful discovery experiences which enable the end user to explore and determine if desired POI categories such as coffee shops, restaurants, shopping, etc. are around a provided location.

Request URI

Request URI	Supported Methods
/v5/discover/category/json	GET, POST

GET

Use the optional category query param with a parent category id to limit the discovery to child categories of that parent. For example: providing the parent id for ‘restaurants’ will enable discovery of all cuisine type categories.

Request Parameters

Name	Description	Required
location	Geo-coordinate of the user location (latitude and longitude separated by ",").	Yes
category	Category id	No
limit	Number of results in response. Default value: 10	No
locale	The preferred language for the response content.	No
user_id	The id associated with the user who is sending the request.	No

Request Example

{host}/entity/v5/discover/category/json?locale=en-US&location=37.12419%2C-121.98828&category=2040&limit=5

POST

The EntityDiscoverCategoryRequest object allows customizing the request. Use optional category property with a parent category id to limit the discovery to child categories of that parent. For example: providing the parent id for ‘restaurants’ will enable discovery of all cuisine type categories.

Request Body

Name	Data Type	Required/Optional	Description
requestParam	EntityDiscoverCategoryRequest	required	Request object to customize the request.

Request Example

{
  "category":"2041",
  "location":{
    "latitude":37.78509,
    "longitude":-122.41988
  },
  "filters":{
    "geo_filter":{
      "type":"radius",
      "radius_in_meter":2000
    }
  },
  "limit":5
}

Response Body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	Status	required	Status
response_time	Number	required	Response time in milliseconds.
reference_id	String	required	Reference id associated with response.
results	[ Category ]	required	List of results that match search criteria.

Response Example

{
  "status":{
    "code":12200,
    "message":"SUCCESS"
  },
  "response_time":6,
  "reference_id":"93739920-4f32-4b64-b358-f5f634913c08",
  "results":[
    {
      "id":"229",
      "name":"American Restaurant"
    },
    {
      "id":"236",
      "name":"Burgers"
    },
    {
      "id":"241",
      "name":"Coffee Houses"
    },
    {
      "id":"261",
      "name":"Mexican Restaurant"
    },
    {
      "id":"263",
      "name":"Pizza"
    }
  ]
}

Status Code

Code	Message	Description
12200	SUCCESS	Indicates that no errors occurred.
12400	INVALID_REQUEST	Indicates either that a required parameter is missing or value of a parameter cannot be parsed.
12500	INTERNAL_SERVER_ERROR	Indicates technical difficulties on API.

Get Categories

The get categories feature provides the developer access to the full category hierarchy. Use this method to retrieve available categories including their ids and level in hierarchy. This feature can be used to build a hierarchical interface for the application or just as a tool to acquire the full Telenav hierarchy. Since this method does not have any spatial context the developer does not need to set a location nor provide other input parameters.

Request URI

Request URI	Supported Methods
/v5/category/json	GET, POST

GET

Request Parameters

Name	Description	Required
locale	Locale to indicate the preferred language for the response content.	No
user_id	The id associated with the user who is sending the request.	No

Request Example

1	`{host}/entity/v5/category/json?locale=en-US`

POST

Request body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
requestParam	EntityGetCategoriesRequest	optional	Request object to customize the request.

Request Example

{"locale":"en-US"}

Response Body

Top-level JSON object:

Name	Data Type	Required/Optional	Description
status	Status	required	Status
response_time	Number	required	Response time in milliseconds.
reference_id	String	required	Reference id associated with response.
results	[ Category ]	required	List of results that match search criteria.

Response Example

{
  "status":{
    "code":12200,
    "message":"SUCCESS"
  },
  "reference_id":"5f209e00-889d-49a5-9e65-ca5c278a4c41",
  "response_time":1,
  "results":[
    {
      "id":"901026",
      "name":"Virtual ATM",
      "child_nodes":[
        {
          "id":"919",
          "name":"ATMs"
        }
      ]
    },
    {
      "id":"900163",
      "name":"Virtual Bars/Clubs",
      "child_nodes":[
        {
          "id":"165",
          "name":"Bars"
        },
        {
          "id":"167",
          "name":"Night Clubs"
        }
      ]
    }
  ]
}

Status Code

Code	Message	Description
12200	SUCCESS	Indicates that no errors occurred.
12500	INTERNAL_SERVER_ERROR	Indicates technical difficulties on API.