/**
     * This function provides a generic way of building a request URL for a
     * range of APIs. Vendor specific elements are contained within the
     * $transform and $this->apiurl variables, which should be overridden
     * when this class is extended.
     * 
     * @param array $request this array contains each of the request fields.
     * @return string The returned string will be the URL, which we should make
     * a request to the supplier's API using.
     */
    protected function buildUrl(array $request) {
        /**
        * $transform takes the following format:
        *
        * $transform = array(
        *  'OPERATION-NAME'    => 'OPERATION-NAME',
        *  'descriptionSearch' => 'descriptionSearch',
        *  'postcode'          => 'buyerPostalCode',
        *  'StartTimeFrom'     => 'itemFilter(<NUM>).name=StartTimeFrom&itemFilter(<NUM>).value',
        *  'endtimeto'         => 'itemFilter(<NUM>).name=EndTimeTo&itemFilter(<NUM>).value',
        *  'maxdistance'       => 'itemFilter(<NUM>).name=MaxDistance&itemFilter(<NUM>).value',
        * );
        *
        * This allows a URL to be built without knowledge of the API being included within
        * this this class, so only a different configuration need be loaded.
        */
        $transform = $this->transform;
        
        /**
        * checkRequest ensures that required variables are included in the search,
        * for example, eBay requires that either a category ID, or a search term
        * be included in every API call.
        */
        \Utilities\Utilities::checkRequired(array(
            $transform,
            $request,
            $this->apiurl,
        ));
        
        foreach ($request as $id => $requestfield) {
            if(array_key_exists($id, $transform)) {
                $id = $transform[$id];
            }
            $this->searchParams[$id] = $requestfield;
        }
        unset($id);
        
        $url = "{$this->apiurl}?";
        $number = 0;
        
        /**
         * $transform is the full list of possible URL fields that are acceptable
         * by the API, they allow us to use friendly names up until this point,
         * and at this point substitute long, search provider specific names.
         */
        foreach ($transform as  $id) {
            if(isset($this->searchParams[$id])) {
                if($id == 'categoryId' && !is_array($this->searchParams[$id]) &&
                        preg_match("/[0-9,]+/", $this->searchParams[$id])) {
                    $this->searchParams[$id] = explode (',',$this->searchParams[$id]);
                }
                if($id == 'categoryId' && is_array($this->searchParams[$id])) {
                    foreach($this->searchParams[$id] as $category) {
                        $url .= "$id=".urlencode($category)."&";
                    }
                }
                else if(!($id == 'categoryId' && !is_numeric($this->searchParams[$id]))) {
                    $oldId = $id;
                    /**
                    * To allow API calls to use URL arrays, we use a <NUM> identifier, 
                    * which then gets substituted for a number, allowing any combination
                    * of possible parameters to be used.
                    */
                    if(preg_match('#(<NUM>)#', $id)) {
                        $id = preg_replace('#(<NUM>)#', $number, $id);
                        $number++;
                    }
                    $url .= "$id=".urlencode($this->searchParams[$oldId])."&";
                }
            }
        }
        
        $url = trim($url,'&');
    	unset($id);
        return $url;
    }