Locations

Retrieve Locations

Retrieving a single location is pretty straightforward. You'll just use the id of locations to get it. When you are retrieving multiple locations, you can either request the full list of locations which will require pagination depending on how many locations you have available. If you just want a list of address or to check which locations a user has access to, you can pull from the cache, which will give you much faster results.

Retrieve Location

GET

`/v1/locations/:location`

Get a single location using its id.

        const response = await fetch("https://api.packagex.io/v1/locations/loc_czhgjrk5JaVvyATPDbyURp", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
});

const location = response.data;

List Locations

Cache

GET

`/v1/locations?cache=1`

You'll get all location cache objects without the need for pagination and much faster latency.

        const response = await fetch("https://api.packagex.io/v1/locations?cache=1", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const locations = response.data;

Example

GET

`/v1/locations`

When you want to retrieve multiple locations, your data property on the result will always be an array even if you don't have any locations.

        const response = await fetch("https://api.packagex.io/v1/locations", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const locations = response.data;
const pagination = response.pagination;

Pagination

If the has_more property on the pagination object is set to true, you know there are more locations in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the the total number of locations in the database.

By default the page is set to 1 and the limit is 25.

If we want to query for locations 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/locations?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const locations = response.data; //the array of locations 25 - 50
const pagination = response.pagination; //the pagination object

Search

There are times when filtering is not enough and you want to find a specific location by some other attribute. In this case, you can do a fuzzy, typo-tolerant search of every location in the database. Below are the properties that are supported by our full text search.

Searchable Properties

name
code
metadata._search

To search, simply provide a string to search by using the search query param. The results will be order by the most relevant first. If you want to highlight matching search results for a frontend, we provide a special property for search-returned location objects called _search which will have the matched text surrounded with <mark> handles.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

        const response = await fetch("https://api.packagex.io/v1/locations?search=newyork", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const location = response.data[0];
console.log(location._search); //Special _search property

Retrieve Locations