LocationService

This gem interfaces with the FedEx Location Services API.

Installation

Add this line to your application's Gemfile:

gem 'fedex_location_service'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fedex_location_service

Usage

In order to use the FedEx API you will need to sign up for a FedEx Webservices account and receive your own test and production credentials.

These credentials can be configured by using the following configuration block:

FedexLocationService.configure do |c|
  c.wsdl           = 'WSDL URL'
  c.key            = 'KEY'
  c.password       = 'PASSWORD'
  c. = 'ACCOUNT NUMBER'
  c.meter_number   = 'METER NUMBER'
end

In order to build a message to pass to the FedEx API you will need to create an address object that resonds to the following:

  • address_one
  • address_two
  • city
  • state
  • postal_code

This can be done with a Struct or with active_record model. This can then be passed to FedexLocationService::Message.build() to generate the proper SOAP message.

Example:

Address = Struct.new(:address_one, :address_two, :city, :state, :postal_code)

addr = Address.new('6008 W Broad St.', nil, 'Richmond', 'VA', '23230')

message = FedexLocationService::Message.build(addr)

The resulting message can then be passed to FedexLocationService::Request.call().

response = FedexLocationService::Request.call(message)

This will return a Savon::Response or Savon::SOAPFault object.

This retuned Savon object can then be passed to FedexLocationService::Response.build()

parsed_response = FedexLocationService::Response.build(response)

Depending on how the request went the parsed_response will have a different status:

## The address was correct and there are FedEx locations:
parsed_response[:search_locations_reply][:highest_severity] == 'SUCCESS'

## The address was correct and there are no FedEx locations:
parsed_response[:search_locations_reply][:highest_severity] == 'ERROR'

## There was a SOAP Fault:
parsed_response[:search_locations_reply][:highest_severity] == 'FATAL'

Included is a FedexLocationService::Locations.call() method that will extract the first 5 closest locations and return the addresses, distance and a map image.

locations = FedexLocationService::Locations.call(response)

locations.first =

{
  :company_name => "Walgreens 3685",
  :street       => "5802 W Broad St",
  :city         => "Richmond",
  :state        => "VA",
  :postal_code  => "23230",
  :distance     => "0.275",
  :map_url      => "https://maps.googleapis.com/maps/api/staticmap?size=350x350&zoom=15&markers=color:blue%7Clabel:A%7C37.59091,-77.50386&maptype=roadmap&sensor=false"
}

For convenience there are both production and test .wsdl files located in the the spec/doc directory for the version of the FedEx Web Services Location Service version (currently Version 7) that this gem is tested against.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/odin/fedex_location_service/issues.

License

The gem is available as open source under the terms of the MIT License.