duffelhq / duffel-api-javascript

Hi,

I understand the need for a different type for the segments on OfferSlices and OrderSlices, due to some fields being unavailable before placing an order, or others being irrelevant after the order is placed, but I'm interested to know more about why OfferSliceSegment destinations/origins are Airports, but on the OrderSlice segments they are Places, implying they could be a City instead.

Looking at the docs it actually seems the destination/origin type is intended to be a Place, even on the offer. What does it mean for a segment to arrive at or depart from a city?

Finally, many of the fields on City are marked as nullable or even undefined, though the docs specify them as required and not nullable (e.g. latitude, longitude, timezone)

Thanks in advance 👍

Hi, thank you for reporting these.

Destinations on offers should be airports, not places. I believe that should be fixed now:

I think cities are only required to have 4 fields: https://duffel.com/docs/api/v1/cities
The rest might be where it can actually be a place instead.

Does that help?

Hi,

Thanks for the extra clarification!
Am I right in saying that in that case the lines below should read destination: Airport and origin: Airport instead?

duffel-api-javascript/src/booking/Orders/OrdersTypes.ts

Line 237 in 217561d

destination: Place

duffel-api-javascript/src/booking/Orders/OrdersTypes.ts

Line 273 in 217561d

origin: Place

This would make them match up with the types on the Offer Slice Segments:

duffel-api-javascript/src/booking/Offers/OfferTypes.ts

Line 464 in 217561d

destination: Airport

Less relevant to my use case, but should Slice origin's and destination's also be only Airports?
i.e. in these places:

duffel-api-javascript/src/booking/Offers/OfferTypes.ts

Line 368 in 217561d

destination: Place

duffel-api-javascript/src/booking/Orders/OrdersTypes.ts

Line 303 in 217561d

destination: Place

With regards to the cities, that all makes sense. Should the City type reflect that is does not have these fields?

duffel-api-javascript/src/types/shared.ts

Lines 37 to 54 in 217561d

    
             time_zone?: string | null 
        
             /** 
        
              * The longitude position of the airport represented in [Decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees) with 6 decimal points with a range between -180° and 180° 
        
              */ 
        
             longitude?: number | null 
        
             /** 
        
              * The latitude position of the airport represented in [Decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees) with 6 decimal points with a range between -90° and 90° 
        
              */ 
        
             latitude?: number | null 
        
             /** 
        
              * The 3-letter IATA code for the city where the place is located. 
        
              * Only present for airports which are registered with IATA as belonging to a [metropolitan area](https://portal.iata.org/faq/articles/en_US/FAQ/How-do-I-create-a-new-Metropolitan-Area). 
        
              */ 
        
             iata_city_code?: string | null 
        
             /** 
        
              * The name of the city (or cities separated by a `/`) where the airport is located 
        
              */ 
        
             city_name?: string | null

duffel-api-javascript/src/types/shared.ts

Line 12 in 217561d

type?: 'city'

Thanks again for spending some time looking into this! 🙏

Sorry for the delayed response!
I think you're right about the origin & destinations on order segments and the city type, I've made a PR here: #896
I'm less sure about the slice origin & destinations - for now I'll keep those as matching the docs but will check with the team internally.

Thank you, that looks great 👍

That PR is merged so I'll close this for now but feel free to open (or another issue) if something comes up :)

	time_zone?: string \| null
	/**
	* The longitude position of the airport represented in [Decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees) with 6 decimal points with a range between -180° and 180°
	*/
	longitude?: number \| null
	/**
	* The latitude position of the airport represented in [Decimal degrees](https://en.wikipedia.org/wiki/Decimal_degrees) with 6 decimal points with a range between -90° and 90°
	*/
	latitude?: number \| null
	/**
	* The 3-letter IATA code for the city where the place is located.
	* Only present for airports which are registered with IATA as belonging to a [metropolitan area](https://portal.iata.org/faq/articles/en_US/FAQ/How-do-I-create-a-new-Metropolitan-Area).
	*/
	iata_city_code?: string \| null
	/**
	* The name of the city (or cities separated by a `/`) where the airport is located
	*/
	city_name?: string \| null

Question: What is the reason for different `origin`/`destination` types on `OfferSlice`/`OrderSlice` `Segment`s?