Watson Data Kit for travel POI

Beta

Watson Data Kit for travel POI

+ Day(s) remaining in the trial

Overview

The Watson Data Kit for travel points of interest (POI) provides access to location, description, images, and additional details of POI's around the world. Through this API, information on any particular attraction can be organized by category, combined with data on any country it may be associated with, filtered for refinement, ranked along weights of your choosing, or used to extract meaningful content through entities, keywords, and concepts.

Getting started

Environments

### Environments 1. Set `{env}` in `Base URL` - Replace `{env}` with either `1` or `2` for any API calls. - Either of the following are acceptable for `Base URL`: - https://wck-1.us-south.containers.mybluemix.net/travel/v1 - https://wck-2.us-south.containers.mybluemix.net/travel/v1

Authentication

### Get Service Credentials 1. Go to the [Watson Data Kits](https://console.bluemix.net/catalog/services/watson-data-kits) and either sign up for a free IBM Cloud account or log in. 2. After you login in, click **Create** and you will be taken to the dashboard page for this service instance. 3. On the sidebar, navigate to **Service credentials** tab. 4. Use **New credential** button on this page to create credentials. In creating credentials you can use default settings or provide your own. Click **Add** to continue. 5. Once you have submitted the form for creating credentials, go to **View credentials** under the Actions column to view your credentials in JSON form. 6. Please note and store `apikey` and `instance_id` fields. You will need `apikey` to request an Access Token for access to the API. You will need an `instance_id` and `url` to make API calls. ### Request an Access Token 1. Issue the following command. - Replace `{apikey}` with the API Key provided in **Service credentials** ```bash curl -X POST \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "Accept: application/json" \ -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey={apikey}" \ "https://iam.bluemix.net/identity/token" \ ``` 2. Save the `access_token` in the response body. To Authenticate any request, provide this `access_token` as a Bearer Token through the `Authorization` header and provide the `instance_id` you obtained earlier through the custom header `Instance-ID`. This is what these headers would look like as part of cURL command: ```bash curl -X GET \ -H "Authorization: Bearer {access_token}" \ -H "Instance-ID: {instance_id}" \ ```

Filtering

The order of results returned is based on the filtering and ranking specified for query parameters. Some parameters have `rank` AND `filter` while other parameters can exclusively take `rank` OR `filter` options. The final ranking of each result in the response array is based on the sum of the `rank` values for all parameters. This is indicated in the output field `rank` for that result object. The number of results returned for any query is based on the `output_limit` query parameter, which is set to `100` by default for each endpoint. ## Advanced Parameter Value Options Prefix a value with the following advanced options enclosed by backtick characters: 1. `` `f` `` for **filter** option This option indicates that the condition set by the parameter it prefaces must be met in order to be included in the result. - **Note:** Each parameter has a **`` `f` `` option added by default.** - _Example_: In `` /attractions?location=37.773972,-122.431297&attraction=`f`theater ``, the response will return only attractions whose name includes the keyword `theater`. 2. `` `u` `` for **unfilter** option This option indicates that the condition set by the parameter it prefaces is not required, but is preferred (i.e. the final `rank` of that result will be effected). - _Example_: In `` /attractions?location=37.773972,-122.431297&attraction=`u`hall ``, the response will include relevant attractions but prefer those that include the keyword `hall` in their names. 3. `` `{0,100}` `` for **rank** option This option specifies the rank of the parameter it prefaces where `rank` is a numeric value in the range [0,100]. - **Note:** Each parameter has a **```rank``` option set to `100` by default.** - _Example_: In `` /attractions?location=37.773972,-122.431297&attraction=`20`theater ``, `` `20` `` the rank value of `attraction` is set to `20`, weighing this parameter less than its default of `100`. - _Example_: In `` /attractions?location=37.773972,-122.431297&radius_miles=`0`1 `` the rank value of `radius_miles` is set to `0`, giving no weight to this parameter and effectively returning all Final rank = ((radius - distance) / radius) * rank value 4. Combined Options The options above may be combined. **Note:** the ```rank``` option must come last. `location` and `radius_miles` parameters only have `` `f` `` option available. - _Example_: In `` /attractions?location=37.773972,-122.431297&attraction=`u25`theater ``, the response will include attractions in results whose names match the keyword `theater` AND have the rank value of `attraction` set to `25`.

Image Licensing and DMCA

All images obtained through Watson Data Kit for travel POI use the CC-BY License. Using any images obtained from this API requires attribution with the following conditions: If You Share the Licensed Material (including in modified form), You must: A. retain the following if it is supplied by the Licensor with the Licensed Material: i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated); ii. a copyright notice; iii. a notice that refers to this Public License; iv. a notice that refers to the disclaimer of warranties; v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable; B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License. You may satisfy the conditions in Section A in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information. If you believe any images obtained through this API are in violation of copyright law, please review [our DMCA policy](https://www.ibm.com/legal/us/en/dmca.html) to contact the appropriate agent and we will gladly remove the offending images immediately upon receipt of valid proof of copyright infringement.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Global Parameters

This section contains global variables, which apply to all of the endpoint definitions of this API. You can use this section to set these variables once, and have the values pre-filled for every endpoint in the Documentation section. The values set can be used with the built-in testing. You can always override the value in the endpoint definition of the Documentation section.
Global variables

environment name used to point to a specific cluster in stage or production environments

Documentation

Watson Data Kit for travel POI:

Attractions

Get all Attractions.
The Attractions endpoint returns information about attractions based on location.

GET   /attractions

			https://wck-{env}.us-south.containers.mybluemix.net/travel/v1/attractions
		
Keys
Global variables

env

BASEURL , required

environment name used to point to a specific cluster in stage or production environments

Path and Query parameters

attraction

STRING , optional

Keyword to filter attractions by name.

category

STRING , optional

Keyword to filter attractions by a category they belong to.

location

STRING , required

Longitude and Latitude geocoordinates expressed in decimal degrees, separated by a comma. Longitude must be in the range [-180.0, +180.0]. Latitude must be in the range [-90.0, +90.0].

open_at

STRING , optional

Filter attractions by the time (in 24hr format) that they are open during.

output_fields

ARRAY , optional

Comma delimited list of field names to include in the response body.

output_limit

INTEGER , optional

Maximum number of results in the response body.

radius_miles

INTEGER , optional

Using either the provided location paramater as the center of a circle containing all possible resulting attractions, this is the length of that circle's radius in miles.

return_nlu

ARRAY , optional

Comma delimited list of which Natural Language Undersanding fields to include in the response body.

source

STRING , optional

Host name of a source url.

watson_nlu

STRING , optional

Search for terms that were obtained using Watson Natural Language Understanding. The parent fields are: `keywords`, `concepts` and `entities`. A selected parent field must be combined with a child field in dot notation as in the format `parent.child`. This must be followed by a `:` and the query term, which must be enclosed in double quotes `" "`. The final format would be `parent.child:""`. Examples: 1. `keywords.text:"statue"` 2. `entities.type:"National Park"` 3. `concepts.relevance:"1"` Please see [NLU API documentation](https://www.ibm.com/watson/developercloud/natural-language-understanding/api/v1/) for all available child field options.

Request code
								
HttpResponse<String> response = Unirest.get("https://wck-1.us-south.containers.mybluemix.net/travel/v1/attractions?location=string&attraction=string&category=string&radius_miles=50&open_at=string&source=string&watson_nlu=string&return_nlu=undefined&output_limit=100&output_fields=undefined") .header("authorization", "REPLACE_KEY_VALUE") .header("instance-id", "REPLACE_KEY_VALUE") .asString();
Response model

200

A JSON array of attraction objects. The fields and number of rows returned are based on the output parameters.

Body

address

object , optional

The address of the attraction, broken down into individual components.

categories

ARRAY , optional

An array of categories the attraction belongs to.

description

STRING , required

distance_miles

DOUBLE , required

The distance (miles) from the input location position to the attraction.

hours

object , optional

Hours object

id

STRING , required

image_info

object , optional

Image information associated with the attraction. Images are provided under the CC-BY License.

location

object , optional

name

STRING , required

The name of the attraction.

phone

STRING , required

The phone number of the attraction, including a prefixed country calling code.

prices

object , optional

Prices object

rank

DOUBLE , required

The final ranking is the sum of the rank values for all parameters.

tags

ARRAY , optional

A collection of tags attributed to the attraction.

url

STRING , required

URL to the attraction's source.

address_string

STRING , required

The full address of the attraction.

city

STRING , required

The city the attraction is located in.

country

STRING , required

The country the attraction is located in.

country_code

STRING , required

The standardized country code of the country the attraction is located in. This is the two-letter code derived from the ISO 3166-2 (part of the ISO 3166 standard).

county

STRING , required

The county the attraction is located in.

neighbourhood

STRING , required

The neighbourhood the attraction is located in.

postcode

STRING , required

The postcode (i.e. postal code, ZIP Code) of the attraction's address.

state

STRING , required

The state the attraction is located in.

road

STRING , required

The name of the road or street the attraction is located at.

house_number

STRING , optional

The house or street number used to identify where on its road or street the attraction is located.

monday

STRING , optional

Hours of operation on Monday.

tuesday

STRING , optional

Hours of operation on Tuesday.

wednesday

STRING , optional

Hours of operation on Wednesday.

thursday

STRING , optional

Hours of operation on Thursday.

friday

STRING , optional

Hours of operation on Friday.

saturday

STRING , optional

Hours of operation on Saturday.

sunday

STRING , optional

Hours of operation on Sunday.

images

ARRAY , optional

A collection of image resources associated with the attraction.

attribution

object , optional

Appropriate attribution information required for usage of the image.

license

STRING , optional

Name of the license the attribution uses.

sizes

object , optional

A collection of resized versions of the original image.

source_url

STRING , optional

URL to the source image.

caption

STRING , optional

Caption used by the source.

source_id

STRING , optional

owner

STRING , optional

Name of the original image owner.

owner_url

STRING , optional

URL to the original image owner's image.

license_link

STRING , optional

URL for license the attribution uses.

attribution_link

STRING , optional

URL the attribution references.

format

STRING , optional

Format the attribution follows.

license_text

STRING , optional

Name of the license the attribution uses.

attribution_text

STRING , optional

Text of attribution to original owner.

medium

object , optional

Details about the medium-sized image.

original

object , optional

Details about the original-sized image.

thumbnail

object , optional

Details about the thumbnail-sized image.

url

STRING , optional

URL for medium-sized image.

width

DOUBLE , optional

Width in pixels.

height

DOUBLE , optional

Height in pixels.

bytes

STRING , optional

Size in bytes.

format

STRING , optional

File extension type.

url

STRING , optional

URL for original-sized image.

width

DOUBLE , optional

Width in pixels.

height

DOUBLE , optional

Height in pixels.

bytes

STRING , optional

Size in bytes.

format

STRING , optional

File extension type.

url

STRING , optional

URL for thumbnail-sized image.

width

DOUBLE , optional

Width in pixels.

height

DOUBLE , optional

Height in pixels.

bytes

STRING , optional

Size in bytes.

format

STRING , optional

File extension type.

lat

DOUBLE , required

lng

DOUBLE , required

general

STRING , optional

Price of admission into the attraction.

seniors

STRING , optional

Price of admission into the attraction for Seniors.

adults

STRING , optional

Price of admission into the attraction for Adults.

children

STRING , optional

Price of admission into the attraction for Children.

400

Bad request.

Body

401

Unauthorized.

Body

default

Unexpected error.

Body

Response example

200

A JSON array of attraction objects. The fields and number of rows returned are based on the output parameters.

								[{
  "address" : {
    "address_string" : string,
    "city" : string,
    "country" : string,
    "country_code" : string,
    "county" : string,
    "neighbourhood" : string,
    "postcode" : string,
    "state" : string,
    "road" : string,
    "house_number" : string
  },
  "categories" : [string],
  "description" : string,
  "distance_miles" : double,
  "hours" : {
    "monday" : string,
    "tuesday" : string,
    "wednesday" : string,
    "thursday" : string,
    "friday" : string,
    "saturday" : string,
    "sunday" : string
  },
  "id" : string,
  "image_info" : {
    "images" : [{
    "attribution" : {
    "license_link" : string,
    "attribution_link" : string,
    "format" : string,
    "license_text" : string,
    "attribution_text" : string
  },
    "license" : string,
    "sizes" : {
    "medium" : {
    "url" : string,
    "width" : double,
    "height" : double,
    "bytes" : string,
    "format" : string
  },
    "original" : {
    "url" : string,
    "width" : double,
    "height" : double,
    "bytes" : string,
    "format" : string
  },
    "thumbnail" : {
    "url" : string,
    "width" : double,
    "height" : double,
    "bytes" : string,
    "format" : string
  }
  },
    "source_url" : string,
    "caption" : string,
    "source_id" : string,
    "owner" : string,
    "owner_url" : string
  }]
  },
  "location" : {
    "lat" : double,
    "lng" : double
  },
  "name" : string,
  "phone" : string,
  "prices" : {
    "general" : string,
    "seniors" : string,
    "adults" : string,
    "children" : string
  },
  "rank" : double,
  "tags" : [string],
  "url" : string
}]
							

400

Bad request.

								
							

401

Unauthorized.

								
							

default

Unexpected error.

								
							

Loading content...

Resources