Import / Export

Each listing type in the administrator panel "Administrator - Content - Listing Type" includes export and import facilities you can use to export your listings to a CSV file or import listings of a different phpListings installation or any 3rd party software that supports listings export.


Exporting Listings.

To export listings of a listing type use the Export facility "Administrator - Content - Listing Type - Export". It produces a CSV file that includes complete listing field data. Note that you can filter listings by category and product / pricing level. To be able to import this data into a different phpListings installation make sure to select all required fields you can find in the list below. The exported data includes the header - first line in the CSV file that describes the exported fields and their value position in a row. You may want to remove the header when importing this data to a 3rd party software, please, consult that software manual on the import file structure.


Importing Listings.

With the help of the import tool "Administrator - Content - Listing Type - Import" you can import listings and user accounts of a different phpListings installation or any 3rd party software that supports data export. This tool accepts comma delimited CSV file and requires the header - first line in the CSV file that describes included listing or account fields and indicates their position in a raw. You can find the list of required fields for your listing type in the "Imported Data Required Fields." section below.

When initiating the import you must specify the pricing level to use for all imported listings as there is no way to set the pricing level for the listing via the CSV file. It is also required to select the user account to use as a default listing owner. Please note that you can include account data into the CSV file, see the "Importing Listings with Accounts." section below. You can also make all imported listings approved or claimed with the "Mark as Approved" and "Mark as Claimed" options enabled. Once the form is submitted the header validation process starts. The tool will accept CSV file with properly formatted header that includes all required field names and does not have duplicates.

The import is done in the background and you can monitor the process on the imports page. The initial status of the import process is "Queued". Expect the scheduled task to execute and flag the import as "Running" within 5 minutes. When the import is done it is flagged as "Done" and a "Log" download button appears.


Imported Data Required Fields.

If you import your data using the CSV file exported from a different phpListings installation make sure that you have recreated the custom form fields for the listing type using the same field name and type for the data to be imported successfully. If you do not have the custom field added into the new installation the field data will be ignored.

Here is the complete set of required fields that must be included into the CSV file to be accepted by the import tool:

Field NameNotes
category_idListing category name, use "->" as a level delimiter, e.g.: "Business->Consulting".
titleListing title.
slugA unique slug (friendly URL) to use in the listing URL, e.g.: https://domain.com/listings/imported-listing-slug Please note that this field value must be unique. The listing is ignored if slug already appears in the listings table.
short_descriptionListing summary, may be left empty.
descriptionListing description, may include the following HTML tags: <h1><h2><h3><h4><h5><strong><b><i><em><ul><ol><li><p><code><pre><span><br> or may be left empty.
meta_titleListing meta title value for SEO, may be left empty.
meta_keywordsListing meta keywords value for SEO, may be left empty.
meta_descriptionListing meta description value for SEO, may be left empty.
timezoneListing timezone, used for Opening Hours and date/time fields of a listing. Accepts the following format: "+0000". The value can be negative or positive, e.g.: "-0330" that means UTC-3:30. Must always include 4 digits and be prefixed with a sign even for positive value, e.g.: "+1245" means UTC+12:45.

If you import data for the "Event" listing type, make sure to include the following fields that are required:

Field NameNotes
event_start_datetimeThe event start UTC date/time in the following format: YYYY-MM-DD HH:MM:SS, e.g.: 2021-12-31 23:59:00
event_frequencyEvent frequency, accepts the following values only: "once", "daily", "weekly", "monthly", "yearly", "custom".
event_intervalEvent interval, must be an integer value of the following range: 1-31.
event_weekdaysEvent weekdays, accepts an integer of 1 to 7 representing the day of week. Use 1 for Monday, 7 for Sunday. Multiple values must be delimited with comma.
event_weeksEvent weeks, accepts integer representation of the week number, 1 for first week, 2 for second, 3 for third, 4 for forth and 5 for fifth. Multiple values must be delimited with comma.
event_datesIs used to store comma delimited dates if "custom" event_frequency is specified. Leave empty otherwise.
event_end_datetimeThe event end UTC date/time in the following format: YYYY-MM-DD HH:MM:SS, e.g.: 2021-12-31 23:59:00
event_rsvpReserved field, please leave empty.

For the "Offer" listing type the following fields are required:

Field NameNotes
offer_start_datetimeThe offer start UTC date/time in the following format: YYYY-MM-DD HH:MM:SS, e.g.: 2021-12-31 23:59:00
offer_end_datetimeThe offer end UTC date/time in the following format: YYYY-MM-DD HH:MM:SS, e.g.: 2021-12-31 23:59:00
offer_priceAccepts float and is required: e.g. 99.95
offer_discount_typeMay accept the following options only: "fixed" and "percentage".
offer_discountFor the "fixed" discount type use an integer, e.g: 150.99, for the "percentage" make sure to set the percentage, e.g: 50 as it accepts values from 0 to 100.
offer_countThe number of available offers, integer value, e.g: 1000
offer_termsOffer terms and conditions. May be left empty.
offer_redeemReserved field, please leave empty.

The following fields are required if your listing type has locations enabled:

Field NameNotes
addressListing street address.
zipZIP / Postal Code
location_idWorks similar to "category_id" field, accepts location names delimited by "->". E.g.: "United States->California->Los Angeles". We recommend to include country, state and city into this field.
latitudeListing latitude, e.g.: "53.5500"
longitudeListing longitude, e.g.: "-2.4333"
zoomListing map zoom level, accepts an integer, 0-20.


Imported Data Optional Fields.

There are optional fields you can include into the CSV file:

Field NameNotes
added_datetimeThe UTC listing submission date/time. Current server date/time is used if this field is not included. E.g.: 2005-06-12 14:00:24


Imported Data Format.

The imported data for each form field type must be properly formatted to be correctly processed by the tool. Below is the list of field types available in phpListings with their required format description and notes:

Field NameNotes
CheckboxA comma delimited list of values, e.g.: "Air Conditioned,Fireplace,Wi-Fi". The import tool will search for an existing option with the same name value for this field in the database and use its key to store the data. If this option does not exist in the database a new option with the auto-generated key is created. The auto-generated key is based on the option name, for example "Air Conditioned" option name becomes "airconditioned" option key.
ColorA hexadecimal representation of the color code, e.g.: #BABAF5, the # symbol is required.
DateA date value, must be supplied in the following format: YYYY-MM-DD, e.g: 2021-12-31
DatetimeA date/time value, must be set using the following format: YYYY-MM-DD HH:MM:SS in UTC timezone, e.g: 2021-12-31 16:40:00
DropzoneA comma delimited list of document URLs. The accepted format depends on the Upload Type linked to the field. E.g.: https://example.com/media/1.jpg,https://domain.com/files/test.pdf
EmailAn email address.
HoursA comma delimited list of opening hour values. Each period must include day of week number, start time and end time separated by dash, e.g.: "1-12:00:00-20:00:00,2-12:00:00-20:00:00", where 1 is the day of week - Monday, 12:00:00 is a listing timezone opening time and 20:00:00 is a listing timezone closing time.
Location Map PickerWorks similar to "category_id" field, accepts location names delimited by "->". E.g.: "United States->California->Los Angeles". We recommend to include country, state and city into this field. The import tool will search for an existing location with the same name in the database and use it. If this location does not exist a new location is created.
Multiple SelectWorks similar to the "Checkbox" field described above.
NumberAccepts integer and float numeric values, e.g.: "1" or "99.95"
PhonePhone number, accepts integers, spaces, dashes, round brackets and plus sign.
PriceAccepts integer and float numeric values, e.g.: "1" or "99.95"
RadioWorks similar to the "Checkbox" field but accepts only one value.
RatingAccepts integers 0-5.
SelectWorks similar to the "Checkbox" field but accepts only one value.
TimeA UTC time value, must be formatted as HH:MM:SS, e.g.: 18:30:00
TimezoneThe listing timezone, used for Opening Hours and date/time fields of a listing. Accepts the following format: "+0000". The value can be negative or positive, e.g: "-0330" that means UTC-3:30. Must always include 4 digits and be prefixed with a sign even for positive value, e.g.: "+1245" means UTC+12:45.
ToggleLeave empty for disabled and use "1" for enabled toggle state.
UrlAccepts properly formatted website URL. The field value must include the protocol value, e.g.: https://domain.com/page.html
YoutubeYouTube video URL, e.g.: https://www.youtube.com/watch?v=l482T0yNkeo

If the field value is formatted incorrectly the whole row is skipped and an error message is added into the log file with the record number of the CSV file.


Importing Listings with Accounts.

As stated above you can select the default imported listing owner account. This is also possible to specify the account for each listing individually via the CSV file. As we identify accounts by email only one field is required to link the account to a listing - "account_email". If the user identified by this email exists in the database we use it as an owner for the imported listing. If the account does not exist we create a new one with this email and a random password generated. Please note that this auto-generated account is published (approved), taxable and email verified by default.

You can include the following fields for the account data:

Field NameNotes
account_emailAccount email.
account_first_nameUser First Name.
account_last_nameUser Last Name.
account_timezoneAccount timezone, see timezone format description above.
account_addressStreet address.
account_zipAccount ZIP / Postal code.
account_location_idAccount location, see location format description in the "Imported Data Format" section above.
account_latitudeAccount latitude.
account_longitudeAccount longitude.
account_zoomAccount map zoom level.

All user custom field names must include the "account_" prefix. For example, if you added the "organization" field for your user accounts, make sure to include its name as "account_organization" into the CSV header.

Note that account password is generated randomly and a password reset via email is required for the user to login.


Import Logs.

When the import process is complete the import status gets changed to "Done" and a log download link appears in the import actions list. You may want to download and check the error log to get the list of skipped listings with a detailed description of the issue and the CSV file record number.