Skip to content

Commit

Permalink
Merge pull request #249 from amadeus4dev/citysearch
Browse files Browse the repository at this point in the history 
re-organized the API catalogue
  • Loading branch information
@tsolakoua
tsolakoua authored Nov 7, 2024
2 parents 6c16211 + 564f6a0 commit 4e208de
Show file tree
Hide file tree
Showing 8 changed files with 75 additions and 25 deletions.
67 changes: 63 additions & 4 deletions docs/resources/destination-experiences.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,13 @@

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.

!!! information
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.

| APIs | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [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. |
| [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. |
| [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. |

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.
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.

## Show Travelers the best sights, shops, and restaurants

Expand Down Expand Up @@ -178,3 +176,64 @@ Same as [Points of Interest API](https://developers.amadeus.com/self-service/ca
```bash
curl https://test.api.amadeus.com/v1/shopping/activities/23642
```

## Find a city by keywords

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.

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.

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.

Let's check out the results for keyword `PAR`. We will limit the search scope to `FR` and the number of results to two.

```bash
GET https://test.api.amadeus.com/v1/reference-data/locations/cities?countryCode=FR&keyword=PAR&max=2
```

The results are probably rather predictable:

```json
{
"meta": {
"count": 2,
"links": {
"self": "https://test.api.amadeus.com/v1/reference-data/locations/cities?countryCode=FR&keyword=PAR&max=2"
}
},
"data": [
{
"type": "location",
"subType": "city",
"name": "Paris",
"iataCode": "PAR",
"address": {
"countryCode": "FR",
"stateCode": "FR-75"
},
"geoCode": {
"latitude": 48.85341,
"longitude": 2.3488
}
},
{
"type": "location",
"subType": "city",
"name": "Le Touquet-Paris-Plage",
"iataCode": "LTQ",
"address": {
"countryCode": "FR",
"stateCode": "FR-62"
},
"geoCode": {
"latitude": 50.52432,
"longitude": 1.58571
}
}
]
}
```

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.

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.
3 changes: 0 additions & 3 deletions docs/resources/flights.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@

The **Flights** category contains a wide array of APIs that can help you manage flights, from searching for flight options to actually booking a flight.

!!! information
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.

| APIs | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **Flight booking** |
Expand Down
3 changes: 0 additions & 3 deletions docs/resources/hotels.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,6 @@

The **Hotels** category contains APIs that can help you find the right hotel and complete the booking.

!!! information
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.

| APIs | Description |
|---------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| [Hotel List](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"} | Returns the name, address, geoCode, and time zone for each hotel bookable in Amadeus. |
Expand Down
11 changes: 6 additions & 5 deletions docs/resources/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@

In this section, you'll discover a comprehensive collection of tutorials for each Self-Service API, organized by their respective categories. These tutorials delve into the typical use cases for each API and offer illustrative examples of parameters, along with clear explanations of their function.

| **Tutorial** | **Coverage** |
| **Tutorial** | **Coverage** |
| ----------- | ----------- |
| [Destination Experiences](./destination-experiences.md) | <ul><li>[Points of Interest](https://developers.amadeus.com/self-service/category/destination-content/api-doc/points-of-interest/api-reference){:target="\_blank"}</li><li>[Tours and Activities](https://developers.amadeus.com/self-service/category/destination-content/api-doc/tours-and-activities/api-reference){:target="\_blank"}</li></ul> |
| [Flights](./flights.md) | <ul><li>[Flight Offers Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search){:target="\_blank"}</li><li>[Flight Offers Price](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-price){:target="\_blank"}</li><li>[Flight Create Orders](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}</li><li>[Flight Order Management](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}</li><li>[Seatmap Display](https://developers.amadeus.com/self-service/category/air/api-doc/seatmap-display){:target="\_blank"}</li><li>[Branded Fares Upsell](https://developers.amadeus.com/self-service/category/air/api-doc/branded-fares-upsell){:target="\_blank"}</li><li>[Flight Price Analysis](https://developers.amadeus.com/self-service/category/air/api-doc/flight-price-analysis){:target="\_blank"}</li><li>[Flight Choice Prediction](https://developers.amadeus.com/self-service/category/air/api-doc/flight-choice-prediction){:target="\_blank"}</li><li>[Flight Inspiration Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-inspiration-search){:target="\_blank"}</li><li>[Flight Cheapest Date Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-cheapest-date-search){:target="\_blank"}</li><li>[Flight Availabilities Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-availabilities-search){:target="\_blank"}</li><li>[Travel Recommendations](https://developers.amadeus.com/self-service/category/trip/api-doc/travel-recommendations){:target="\_blank"}</li><li>[On Demand Flight Status](https://developers.amadeus.com/self-service/category/air/api-doc/on-demand-flight-status){:target="\_blank"}</li><li>[Flight Delay Prediction](https://developers.amadeus.com/self-service/category/air/api-doc/flight-delay-prediction){:target="\_blank"}</li><li>[Airport & City Search](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"}</li><li>[Airport Nearest Relevant](https://developers.amadeus.com/self-service/category/air/api-doc/airport-nearest-relevant){:target="\_blank"}</li><li>[Airport Routes API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-routes){:target="\_blank"}</li><li>[Airport On-Time Performance](https://developers.amadeus.com/self-service/category/air/api-doc/airport-on-time-performance){:target="\_blank"}</li><li>[Flight Check-in Links](https://developers.amadeus.com/self-service/category/air/api-doc/flight-check-in-links){:target="\_blank"}</li><li>[Airline Code Lookup](https://developers.amadeus.com/self-service/category/air/api-doc/airline-code-lookup){:target="\_blank"}</li> <li>[Airline Routes](https://developers.amadeus.com/self-service/category/air/api-doc/airline-routes){:target="\_blank"}</li></ul> |
| [Hotels](./hotels.md) | <ul><li>[Hotel List](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"}</li><li>[Hotel Ratings](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-ratings/api-reference){:target="\_blank"}</li><li>[Hotel Search](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"}</li><li>[Hotel Booking](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-booking/api-reference){:target="\_blank"}</li><li>[Hotel Name Autocomplete API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-name-autocomplete/api-reference){:target="\_blank"}</li></ul> |
| [Itinerary Management](./itinerary-managment.md) | <ul><li>[Trip Purpose Prediction](https://developers.amadeus.com/self-service/category/trip/api-doc/trip-purpose-prediction/api-reference){:target="\_blank"}</li><li>[City Search](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"}</li></ul> |
| [Flights](./flights.md) | <ul><li>[Flight Offers Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search){:target="\_blank"}</li><li>[Flight Offers Price](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-price){:target="\_blank"}</li><li>[Flight Create Orders](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}</li><li>[Flight Order Management](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}</li><li>[Seatmap Display](https://developers.amadeus.com/self-service/category/air/api-doc/seatmap-display){:target="\_blank"}</li><li>[Branded Fares Upsell](https://developers.amadeus.com/self-service/category/air/api-doc/branded-fares-upsell){:target="\_blank"}</li><li>[Flight Price Analysis](https://developers.amadeus.com/self-service/category/air/api-doc/flight-price-analysis){:target="\_blank"}</li><li>[Flight Choice Prediction](https://developers.amadeus.com/self-service/category/air/api-doc/flight-choice-prediction){:target="\_blank"}</li><li>[Flight Inspiration Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-inspiration-search){:target="\_blank"}</li><li>[Flight Cheapest Date Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-cheapest-date-search){:target="\_blank"}</li><li>[Flight Availabilities Search](https://developers.amadeus.com/self-service/category/air/api-doc/flight-availabilities-search){:target="\_blank"}</li><li>[Travel Recommendations](https://developers.amadeus.com/self-service/category/trip/api-doc/travel-recommendations){:target="\_blank"}</li><li>[On Demand Flight Status](https://developers.amadeus.com/self-service/category/air/api-doc/on-demand-flight-status){:target="\_blank"}</li><li>[Flight Delay Prediction](https://developers.amadeus.com/self-service/category/air/api-doc/flight-delay-prediction){:target="\_blank"}</li><li>[Airport & City Search](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"}</li><li>[Airport Nearest Relevant](https://developers.amadeus.com/self-service/category/air/api-doc/airport-nearest-relevant){:target="\_blank"}</li><li>[Airport Routes API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-routes){:target="\_blank"}</li><li>[Airport On-Time Performance](https://developers.amadeus.com/self-service/category/air/api-doc/airport-on-time-performance){:target="\_blank"}</li><li>[Flight Check-in Links](https://developers.amadeus.com/self-service/category/air/api-doc/flight-check-in-links){:target="\_blank"}</li><li>[Airline Code Lookup](https://developers.amadeus.com/self-service/category/air/api-doc/airline-code-lookup){:target="\_blank"}</li> <li>[Airline Routes](https://developers.amadeus.com/self-service/category/air/api-doc/airline-routes){:target="\_blank"}</li></ul> |
| [Destination Experiences](./destination-experiences.md) | <ul><li>[Points of Interest](https://developers.amadeus.com/self-service/category/destination-content/api-doc/points-of-interest/api-reference){:target="\_blank"}</li><li>[Tours and Activities](https://developers.amadeus.com/self-service/category/destination-content/api-doc/tours-and-activities/api-reference){:target="\_blank"}</li><li>[City Search](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"}</li></ul> |
| [Cars and Transfers](./cars-transfers.md) | <ul><li>[Transfer Booking](https://developers.amadeus.com/self-service/category/cars-and-transfers/api-doc/transfer-booking/api-reference){:target="\_blank"}</li><li>[Transfer Management](https://developers.amadeus.com/self-service/category/cars-and-transfers/api-doc/transfer-management/api-reference){:target="\_blank"}</li><li>[Transfer Search](https://developers.amadeus.com/self-service/category/cars-and-transfers/api-doc/transfer-search/api-reference){:target="\_blank"}</li></ul> |
| [Market insights](./market-insight.md) | <ul><li>[Flight Most Traveled Destinations](https://developers.amadeus.com/self-service/category/air/api-doc/flight-most-traveled-destinations/api-reference){:target="\_blank"}</li><li>[Flight Most Booked Destinations](https://developers.amadeus.com/self-service/category/air/api-doc/flight-most-booked-destinations/api-reference){:target="\_blank"}</li><li>[Flight Busiest Traveling Period](https://developers.amadeus.com/self-service/category/air/api-doc/flight-busiest-traveling-period/api-reference){:target="\_blank"}</li><li>[Location Score](https://developers.amadeus.com/self-service/category/destination-content/api-doc/location-score/api-reference){:target="\_blank"}</li></ul> |
| [Hotels](./hotels.md) | <ul><li>[Hotel List](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"}</li><li>[Hotel Ratings](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-ratings/api-reference){:target="\_blank"}</li><li>[Hotel Search](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"}</li><li>[Hotel Booking](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-booking/api-reference){:target="\_blank"}</li><li>[Hotel Name Autocomplete API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-name-autocomplete/api-reference){:target="\_blank"}</li></ul> |
| [Itinerary Management](./itinerary-managment.md) | <ul><li>[Trip Purpose Prediction](https://developers.amadeus.com/self-service/category/trip/api-doc/trip-purpose-prediction/api-reference){:target="\_blank"}</li></ul> |
4 changes: 0 additions & 4 deletions docs/resources/itinerary-managment.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,9 @@

In the **Itinerary Management** category, you can give travelers a simple and personalized way to view their itinerary.

!!! information
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.

| APIs | Description |
|------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [Trip Purpose Prediction](https://developers.amadeus.com/self-service/category/trip/api-doc/trip-purpose-prediction/api-reference){:target="\_blank"} | Analyze a flight itinerary and predict whether the trip is for business or leisure. |
| [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. |


## Predict the trip purpose from a flight
Expand Down
Loading

0 comments on commit 4e208de

Please sign in to comment.