|
2 | 2 |
|
3 | 3 | With Amadeus Self-Service APIs, you can find data on over two million places and 150,000 activities and show travelers the best things to see and do. In the **Destination Experiences** category, we have two APIs available for that. |
4 | 4 |
|
5 | | -!!! information |
6 | | - Our catalogue of [Self-Service APIs](https://developers.amadeus.com/self-service){:target="\_blank"} is currently organised by categories that are different to what you see on this page. |
7 | | - |
8 | 5 | | APIs | Description | |
9 | 6 | |------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| |
10 | 7 | | [Points of Interest](https://developers.amadeus.com/self-service/category/destination-content/api-doc/points-of-interest/api-reference){:target="\_blank"} | Find the best sights, shops, and restaurants in any city or neighborhood. | |
11 | 8 | | [Tours and Activities](https://developers.amadeus.com/self-service/category/destination-content/api-doc/tours-and-activities/api-reference){:target="\_blank"} | Find the best tours, activities, and tickets in any city or neighborhood. Includes a deep link to book with the provider. | |
| 9 | +| [City Search](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} | Finds cities that match a specific word or string of letters. | |
12 | 10 |
|
13 | | -These two APIs have the same behavior. You can search by radius or by a square, and retrieve results by ID. Let's go through them one by one. |
| 11 | +The first two APIs have the same behavior. You can search by radius or by a square, and retrieve results by ID. Let's go through them one by one. |
14 | 12 |
|
15 | 13 | ## Show Travelers the best sights, shops, and restaurants |
16 | 14 |
|
@@ -178,3 +176,64 @@ Same as [Points of Interest API](https://developers.amadeus.com/self-service/ca |
178 | 176 | ```bash |
179 | 177 | curl https://test.api.amadeus.com/v1/shopping/activities/23642 |
180 | 178 | ``` |
| 179 | + |
| 180 | +## Find a city by keywords |
| 181 | + |
| 182 | +If you are unsure of the exact spelling of a city, you can reach out to the [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"}. This API uses a keyword, which is a string containing a minimum of 3 and a maximum of 10 characters, to search for a city whose name contains this keyword. It is not critical whether you enter the entire city name or only a part of it. For example, `Paris`, `Par` or `ari` will all return `Paris` in the search results. |
| 183 | + |
| 184 | +There are two optional parameters to help you make the query more precise - `countryCode` and `max`. The `countryCode` is a string for the ISO 3166 Alpha-2 code of the country where you need to locate a city, for example, `FR` for France. The `max` is an integer that defines the maximum number of search results. |
| 185 | + |
| 186 | +You can also include a list of airports for each city returned in the search results. To do this, you need to add `AIRPORTS` to the include field, which is an array of strings defining additional resources for your search. |
| 187 | + |
| 188 | +Let's check out the results for keyword `PAR`. We will limit the search scope to `FR` and the number of results to two. |
| 189 | + |
| 190 | +```bash |
| 191 | +GET https://test.api.amadeus.com/v1/reference-data/locations/cities?countryCode=FR&keyword=PAR&max=2 |
| 192 | +``` |
| 193 | + |
| 194 | +The results are probably rather predictable: |
| 195 | + |
| 196 | +```json |
| 197 | +{ |
| 198 | + "meta": { |
| 199 | + "count": 2, |
| 200 | + "links": { |
| 201 | + "self": "https://test.api.amadeus.com/v1/reference-data/locations/cities?countryCode=FR&keyword=PAR&max=2" |
| 202 | + } |
| 203 | + }, |
| 204 | + "data": [ |
| 205 | + { |
| 206 | + "type": "location", |
| 207 | + "subType": "city", |
| 208 | + "name": "Paris", |
| 209 | + "iataCode": "PAR", |
| 210 | + "address": { |
| 211 | + "countryCode": "FR", |
| 212 | + "stateCode": "FR-75" |
| 213 | + }, |
| 214 | + "geoCode": { |
| 215 | + "latitude": 48.85341, |
| 216 | + "longitude": 2.3488 |
| 217 | + } |
| 218 | + }, |
| 219 | + { |
| 220 | + "type": "location", |
| 221 | + "subType": "city", |
| 222 | + "name": "Le Touquet-Paris-Plage", |
| 223 | + "iataCode": "LTQ", |
| 224 | + "address": { |
| 225 | + "countryCode": "FR", |
| 226 | + "stateCode": "FR-62" |
| 227 | + }, |
| 228 | + "geoCode": { |
| 229 | + "latitude": 50.52432, |
| 230 | + "longitude": 1.58571 |
| 231 | + } |
| 232 | + } |
| 233 | + ] |
| 234 | +} |
| 235 | +``` |
| 236 | + |
| 237 | +First of all we see the French capital at the top of the list. The second result refers to the town Le Touquet-Paris-Plage, whose official name contains three letters that match our keyword. If we want to see more results, we can always adjust the `max` number of results. |
| 238 | + |
| 239 | +The main difference between the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} and [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} is that the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} only shows cities that have an airport, while the [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} retrieves any city that matches a keyword. |
0 commit comments