- Who can: a member whose role allows “Create” and “Update” on locations in the “Entities” group
- Where in Cargofy: Locations
What it is
Locations are your warehouses and customs posts. The assistant imports them from a table of up to 1,000 rows, adds a single location, changes them, sets the type and working hours and finds them by name or type.
Important
The assistant cannot delete a location, and it saves an import at once. Before a large table, import two or three rows and check the answer. Ask the assistant to show the column mapping and the country and wait for your yes. An import does not change locations you already have.
What it can do
Locations from start to finish
A dispatcher’s conversation with the assistant and Cargofy’s real answers. The terms are in the Glossary. The tools behind each step are in the table at the end.
1. Import a table
Import these warehouses as locations, country Ukraine, all of them are storage: Warehouse | Address Demo: Lviv warehouse | вулиця Демо, 1, Львів Demo: Zhytomyr warehouse | вулиця Демо, 2, Житомир
Cargofy creates two locations of the type “Storage” and names the city it found for each address: “Львів” for row 2 and “Житомир” for row 3. The header is row 1, so the first warehouse is row 2.
2. Import the table again
Import the same table again.
The two warehouses from step 1 are counted as existing: they are not created twice.
3. Add a customs post
Add a customs post: Demo: Chop customs, Demo street 1, Chop, Zakarpattia Oblast, 89502, Ukraine, 48.4330, 22.1960.
Cargofy saves the location with the type “Customs post” and answers with its name, type and street address.
4. Set working hours
Demo: Chop customs works Monday to Friday, 08:00 to 20:00.
Cargofy saves the hours.
5. Find locations
Show our customs posts.
The assistant lists all the locations of the type “Customs post”, newest first, with the total. When the answer has a next_cursor, the assistant asks for the next page until the list ends.
| Step | Tool | What the assistant sends |
|---|---|---|
| 1 | entities-schema, then facilities-import | mapping {"Warehouse": "name", "Address": "address"}, defaults {"country_id": "ua", "facility_type_id": 1} and the rows, one object per row |
| 2 | facilities-import | the same table |
| 3 | entities-create | facility with name, facility_type_id 2, address_1, city, state, postal_code, country_id, lat, lng |
| 4 | entities-update | work_from "08:00", work_to "20:00", working_day_ids [2, 3, 4, 5, 6] |
| 5 | entities-query | a filter on facility_type_id equal to 2, then the same filter with cursor for each next page |
Import locations from a table
Here are our 40 warehouses with street, city, region and postal code. Import them, country Poland, all of them are storage, open Monday to Saturday 07:00–19:00.
Give the table as rows in the chat or as CSV text. The assistant maps each column to a location field and sends the values that are the same for every row as defaults. Defaults fill only empty cells.
Each row needs a name and an address. Cargofy accepts the address in one of three shapes:
| The table has | What Cargofy does |
|---|---|
| One address column, such as “вулиця Демо, 2, Житомир” | Fills street, city, region, postal code and coordinates |
| Street, city, region and postal code in separate columns | Adds the coordinates; region and postal code are saved as you wrote them |
| Street, city, region, postal code, latitude and longitude | Saves them as given, in any language |
Write the address in the country’s language, with the street and house number: “вулиця Демо, 1, Львів”, “ulica Demo 1, Warszawa”. Check the region and postal code columns before the import.
When a row has latitude and longitude, give the street, city, region and postal code in their own columns.
The country is a two-letter code, such as ua or pl, in a country column too. Give it once for the whole table, or in a country column. A filled country cell wins over the one for the table.
The type, working days and hours can be columns or values for the whole table. In a column, the type is a number: 1 for “Storage”, 2 for “Customs post”. Working days are numbers separated by commas, such as 2,3,4,5,6. Hours are HH:MM, see Set working hours. Name the type for every row or for the table, for example “all of them are storage”.
Read the import result
How did the import go? Send only the failed rows again, the addresses are fixed.
| The answer has | Meaning |
|---|---|
created | how many new locations Cargofy saved |
existing | how many rows match a location you already have. They are not created twice and not changed |
failed | each failed row with its number and reason |
placed | each row whose address Cargofy found, with the city it found, in the country’s language. Rows that came with coordinates are not listed |
aborted | true when Cargofy stopped the import before the end |
A row that matches a location you already have does not change it. So you can send the whole table again or only the fixed rows: only the new rows are created. To change the type or hours of a location you already have, ask for it by name, see Fix a location.
Fix the failed rows by their reasons and send them again. Cargofy can also refuse the whole table before any row is imported, for example for a wrong mapping: the answer gives the reason.
Add one location
Add our warehouse Demo: Brovary cross-dock: Demo street 3, Brovary, Kyiv Oblast, 07400, Ukraine, 50.5150, 30.7950, type storage.
entities-create adds one location. It needs the full address and coordinates: give the name, street address, city, region, postal code, two-letter country code, latitude and longitude. One location by its address is added with facilities-import.
Give the latitude first, then the longitude. The type is “Storage” or “Customs post”. You can add a note.
When you already have this location, Cargofy answers with it and does not create a new one.
Fix a location
Demo: Brovary cross-dock is at Demo street 5, not 3. The pin is 50.5155, 30.7960.
Name the location and what to change. The assistant changes only the fields you name with entities-update. To move a location, give the new address and the new coordinates together.
Set working hours
Demo: Lviv warehouse works Monday to Saturday, 07:00 to 19:00.
The assistant sets the opening and closing time and the working days with entities-update. Times are HH:MM, 24-hour: write 08:00, not 8:00. For a location open until midnight, write 23:59. Night hours such as 22:00–06:00 are accepted: the closing time is on the next day.
A location has one opening time and one closing time for all its working days. Put a different schedule for one day in the note.
Name the days in words. The assistant sends them as numbers from 1, Sunday, to 7, Saturday:
| Days | Numbers |
|---|---|
| Monday to Friday | 2, 3, 4, 5, 6 |
| Monday to Saturday | 2, 3, 4, 5, 6, 7 |
| Every day | 1, 2, 3, 4, 5, 6, 7 |
A change keeps the fields you do not name.
Find locations
Find our locations with “warehouse” in the name. Show our storage locations sorted by name.
| You can ask by | How it works |
|---|---|
| Name | a word from the name: capital letters do not matter. For the exact full name they do |
| Type | “Storage”, “Customs post” or both |
Text search covers the name only. Results come newest first, or by name when you ask. The answer gives the total. Each answer holds 20 locations, or up to 100 when the assistant asks for more, and the total. Newest first, the answer has a next_cursor while more are left: the assistant passes it as cursor in the next call and shows the whole list, not only the first page. For each location the assistant sees the name, the type and the street address.
Name your locations so you can find them, for example with the city in the name.
Glossary
The words of this page, what they mean in Cargofy and the name the assistant works with. Paste this table into the chat or add it to your assistant’s project knowledge: the assistant then reads your words the same way Cargofy does.
| Term | Meaning | The assistant sees |
|---|---|---|
| Location | A warehouse or customs post of your company | the object facility |
| Type | “Storage” or “Customs post” | facility_type_id: 1 “Storage”, 2 “Customs post” |
| One-line address | The whole address in one column. Import only: Cargofy fills the rest of the address and the coordinates | address in mapping |
| Street address | Street and house number | address_1; address_2 for a second line |
| City, region, postal code | Parts of the address | city, state, postal_code |
| Country | Two-letter code, such as ua or pl | country_id |
| Coordinates | Latitude and longitude of the pin | lat, lng |
| Working days | Days the location works, 1 Sunday to 7 Saturday | working_day_ids, for example [2, 3, 4, 5, 6] |
| Opening and closing time | HH:MM, 24-hour | work_from, work_to |
| Note | Free text about the location | note |
| Mapping | Which column of your table goes to which field | mapping in facilities-import |
| Defaults | Values for every row with an empty cell. The country goes here | defaults in facilities-import |
| Import result | What happened to each row | created, existing, failed, placed, aborted |
Limits
- Up to 1,000 rows per import, and 5 MB of CSV text. No Excel files.
- Locations cannot be searched by city, region or address.
- The assistant cannot delete a location.