CarRentalAgentService. Method

Retrieves a set of geographic Regions.

public RegionsResponse (
RegionsRequest request
);

Parameters

RegionsRequest: A RegionsRequest containing the nessessary request data.

Return Value

A RegionsResponse containing the requested Regions.

Remarks

Use this method to get a set of Regions. Mostly you will use this method to find a suitable location for a car rental request. Because the regional struture is a tree-node-like datastructure, you are able to either load the entire region list or only a part of it. Partial loads can be achieved by passing a parent region id, the order of levels, a country code or a name wildcard to load regions for.

To comprehend the responsibility of a Region within the complete car rental process, it may be helpful to imagine the regional structure as a tree-node-like datastructure:

The region datastructure as tree view

Fig: The region datastructure as tree view

To point it out more clearly, Regions are used to categorize geographical areas and group together Locations. Consequently, you will most likely use Regions to search suitable car rental locations.

For example, to get started with the "location finding process", you first can obtain a list of topmost (level 1, root or country level) regions available. Afterwards, you may get the available child regions for a specific root region again using GetRegions.

Another useful way in finding the correct Region would be to specify a Name wildcard. This way you may search and query regions by name. Note that name wildcard search is language-dependent. In addition the search term supports following wildcard patterns:

Supported Wildcard Patterns

Pattern	Description
* (Asterisk)	Matches any character occuring zero or more times in place of pattern.
? (Question Mark)	Matches any character occuring exactly once in place of pattern.

Common Use Case Scenarios

Use Case Scenario	Resolution Path
You want to provide the end user with a list of available regions for selection.	Basic Path Query regions with Level set to 1 to obtain all root (country level) regions. Let the user select a region. Check if selected regions has child regions using the HasChilds property. If child regions exist, query regions with ParentId set to the selected region id and Levels set to 1 to obtain child regions. Repeat step 2-4 until user has selected the "deep-leveled" region having no more child regions. If child regions do not exist and the selected regions has locations assigned, continue your car rental process. Alternate Path Query supported countries using GetCountries method. Let the user select a country. Query all regions of country with CountryCode set to the ISO 3166 two letter country code from selected country. Display a region-based tree structure and let the user only select regions having HasLocations property set to true. Continue your car rental process.
You want to get the direct (subsequent) child regions of a specific region.	Query regions with ParentId set to the parent region's id and Levels set to 1.
You want to get the direct (subsequent) child regions of a specific region, whereby you want the result limited to regions which support a specific LocationMeetingType.	Query regions with ParentId set to the parent region's id and Levels set to 1. Additionally set the MeetingAtAirportPreference, MeetingAtCounterPreference, MeetingAtSpecialAddressPreference as preferred.
You want to check if a region exists for a destination name directly entered by user.	Query regions with Name set to the name entered by user and with LanguageCode set to the ISO 639 two letter language code in which the name is considered to be.

List Of Errors Returned

Error Code	Description
E_INTERNAL_SERVICE	An internal service error occured during the process.
E_TICKET_TOKEN_INVALID	The provided token is invalid. This error occurs if: The token is in invalid format. The token is expired. The token was not found.
E_REGION_NOT_FOUND	The requested regions cannot be found. This error occurs if: There are no childregions exisiting with specified parent region id, country code, name and/or level.
E_PARENT_REGION_NOT_FOUND	The requested parent region cannot be found.
E_COUNTRY_NOT_FOUND	The associated country for specified country code cannot be found.
E_REQUEST_AMBIGIOUS	The performed request ambigious. This error occurs if: Both ParentId and CountryCode parameters were passed. Both ParentId and Name parameters were passed. Both CountryCode and Name parameters were passed. Neither ParentId, CountryCode nor Name parameters were passed.
E_REQUEST_INVALID	The performed request is invalid or malformed.

List Of Warnings Returned

Warning Code	Description
W_LANGUAGE_NOT_SUPPORTED	The requested language code is not supported for localization. Using default language instead.

Example

Example 1: Get a list of toplevel / root regions available (usually countries) in english language

[C#]
RegionsRequest rq = new RegionsRequest();

rq.Ticket = this.serviceTicket;
rq.Operation.Target = OperationTarget.Test;
rq.Level = 1;
rq.LanguageCode = "EN";

RegionsResponse rs = this.service.GetRegions(rq);

foreach (Region rootRegion in rs.Region) 
{
       Console.WriteLine("Root Region {0} = {1}", rootRegion.Id, rootRegion.Name);
}

Example 2: Get all regions for Spain (ES) in german language

[C#]
 RegionsRequest rq = new RegionsRequest();
 rq.Operation.Target = OperationTarget.Test;
 rq.CountryCode = "ES";
 rq.LanguageCode = "DE";

 RegionsResponse rs = this.service.GetRegions(rq);