We'll be using Ruby, Sinatra, and the EasyPost Client Gem in this example application, but this functionality could be integrated into any app written with Python, PHP, Java and other languages supported by the many EasyPost official client libraries.
from_address, and save its ID (
For the purpose of this tutorial, we assume that the website is for an e-commerce business. The
from_address represents the company's shipping location and will not change. Hence, we need to generate an Address separately, and store its ID. You can do so using the client libraries, or using curl on the command line. Check out our Getting Started guide if this is something you haven't done before.
The first thing we need is an API key from EasyPost. This is an example application, so we are going to use the test API key, but be aware that non-test data will still be visible. You can find the test key on the API Keys Page.
Next, create a new directory for your project, and open your favorite code editor and create a new file called
.env in your new folder. Fill in the test EasyPost API key so it looks like this:
We will start out by creating a file named
Gemfile to describe gem dependencies for our Ruby code. A gem is a Ruby package that will install the libraries that we need. Your Gemfile should always be in the root of your project directory, as this is where Bundler, the Ruby dependency manager, expects it to be.
Time to add some gems. Let’s add the
easypost gem to communicate with the API,
sinatra for our web application, and
dotenv to load our configuration values in. Your
Gemfile should look like this:
Install the Gemfile-defined dependencies by running
bundle install from your project root in the terminal.
Now, we can start writing our web application. Create a file called
app.rb and save it to the root directory. This will define the web application. For now, let us add a "Hello World" snippet like below:
We did four things here:
requirestatements import the dependencies that Bundler installed for us.
Dotenv.load: Loads config variables from our
EasyPost.api_key: Assigns our API Key to the EasyPost Class
get '/': Set up a route for the server at
To check if your app is working, run
bundle exec ruby app.rb and you should see the following:
Go ahead and visit
http://localhost:4567/ and you should see the text "Hello world" on the page.
You can stop the application with Ctrl-C. In the next step, we will create a view that displays a form to create a shipment, rendered by the
In order to create a view, make a new directory called views in your project folder. Add a file named
layout.erb to the views folder. The layout will contain the HTML layout that is common to all pages. We can yield the views from the layout. You can add the following content to the layout:
index.erb to the views directory. It will contain a form to enable users to input data for the following:
Considering that there are many fields for each of the above objects, we can create partial views to enable abstracting and reusing certain portions of the form. We can abstract the address input fields into a partial by creating a file inside the views folder named
The form will only include a "To Address" representing the customer address. The "From Address" we will load from
.env, as mentioned at the beginning of the tutorial. To input parcel details, create another partial named
_parcel_details.erb in the views folder and include the fields for parcel details. Here's how you can go about it:
Now we'll hook up the
'/' route to our erb view in
app.rb. Replace the "Hello World" string in
get '/' with
erb :index. This renders the index view we just created.
/ in your browser should look like the below screenshot. Our example repo may have some slightly different css styles, but the HTML and functionality should be the same.
We have a form set up at this point. But, in order to get rates, we need to create a shipment when the form is submitted. Let's create a
POST route adjacent to our
GET route that handles our form submission.
If you'll ship to the same address more than once, consider storing the Address ID for
to_address using the same principle that we used for our
from_address (we recommend leveraging your database in this scenario). This will cut down on response times.
Now that we have a shipment object, we can provide the users with rates to buy the shipment. So let's create a route that retrieves the shipment and renders a page that lists the rates.
app.rb add the following
We still haven't created a rate.erb view. To do so, create a
rate.erb file inside /views that will display the rates.
This code performs a simple iteration over our shipment’s rates array and displays it as a table. The user can choose a rate to buy the shipment.
Verifying an Address before you ship is a great way to reduce issues with delivery. An invalid address may not return correct rates upon creation of shipment. In order to set up address verifications, there are couple of small additions to the above code.
So let's go ahead and set up address verification. Add the following to the last line of the address partial, and replace your current
post '/shipment' route with the code below.
In the above example we have used the
verify_strict verification parameter. EasyPost also provides the option of a
verify parameter. Using the
verify_strict parameter will raise an EasyPost::Error on address verification failures and will not create the address object.
verify always creates the address object with a verification hash containing errors/warnings even if verification fails.
zip4 verification performs CASS Validation and
delivery verification checks that the address is deliverable.
delivery verification may adjust an address or complete a 9 digit zip code based on the USPS address database. For your customers, we suggest that you display the corrected address back to the user and allow them to approve the verified address.
In order to buy a label for a selected rate, create a post route in
The code redirects to a route that isn't set up yet. Let's add a
GET route that will retrieve the shipment and display a link to the shipment label and shipment tracking code on a page. Here's how:
In order to create the label view, add another file in the views folder and name it
shipment.erb. Add the following to the label view.
Yep, that’s it! That’s all the code you need to create and buy shipments.
Let's demonstrate all the functionality that we have added. Let’s run our application!
As before, run
bundle exec ruby app.rb from the project root, and you should see your application start up.
Then just visit
http://localhost:4567 to see it in action!
We simplified things for the purpose of the tutorial, but you can view a more complete example in the repository on GitHub. The sample repo also demonstrates some basic error handling, and would serve as a great starting point to keep building off of!