Manage
Listings &
Events
retro.directory on Twitter retro.directory on Twitter
Homeretro.directory logo

retro.directory API Reference

API Reference

The following commands are available within the API.
To use any of these commands you need an API Key.
All command return suitable HTTP error codes, and some return JSON.

The following may also be useful for reference.


Get Listings
Description: Fetches a basic list listing that this API Key is allowed to manage.
cURL Example:
Command:
curl -X GET -i https://retro.directory/api/v1/listing -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK
[ {"id":12,"name":"My Retro Museum"}, {"id":15,"name":"My Games Shop"} ]
Fields:
  • id: The Unique ID of a listing
  • name: The name of the listing

Get Events
Description: Fetches a basic list of events for a specific listing.
cURL Example:
Command:
curl -X GET -i https://retro.directory/api/v1/listing/<listing id>/event -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK
[ {"id":14,"name":"My First Event","type":10,"start":"2023-05-19","end":"2023-09-01"}, {"id":27,"name":"My Second Event","type":10,"start":"2023-03-19","end":"2023-03-26"} ]
Fields:
  • id: The Unique ID of this event
  • name: The event title
  • type: The event type, see event types for a list
  • start: The event start date, in yyyy-mm-dd format
  • end: The event end date, in yyyy-mm-dd format

Create Event
Description: Creates a new event for a specific listing.
cURL Example:
Command:
Save to create.json:
{ "name": "Event Name", "description": "Event Description", "info": "Further Event Information", "type": 10, "start": "2023-05-19", "end": "2023-09-01", "url": "https://website", "bookingurl": "https://website/booking", "telephone": "+01 234567897", "address": "10 Retro Street, Retroshire", "postcode": "02832", "country": "GB", "lat": 51.477928, "lng": -0.001545, "lookupaddress": true, "places": 25, "showplaces": true, "onlineonly": false, "showowner": true, "uselistingicon": true, "refreshurl": "", "social": { "fb": "https://facebook.com/facebookgroup" } }
curl -X POST -i https://retro.directory/api/v1/listing/<listing id>/event -H "Authorization: bearer <api-key>" -d @create.json
Fields:
  • name: The event title
  • description: The event description
  • info: Further information about the event.
  • type: The event type, see event types for a list
  • start: The event start date, in yyyy-mm-dd format
  • end: The event end date, in yyyy-mm-dd format
  • url: A website URL with more information about the event
  • bookingurl: A website URL that takes you directly to ticket purchases
  • telephone: Contact telephone number for more information
  • address: Address for the event
  • postcode: Postal / Zip code for the event address
  • country: Event address country as an ISO 3166 Alpha-2 Code country code.
  • lat: Geographic latitude of the event (for the map)
  • lng: Geographic longitude of the event (for the map)
  • lookupaddress: Boolean, true/false. If true, latitude and longitude will be looked up (Geocoding) using the address
  • places: Number of tickets/places available. This can be updated later. 0=Sold out
  • showplaces: Boolean, true/false, if the number of tickets/places should be displayed.
  • onlineonly: Boolean, true/false, if true, the event is virtual/online - address/map is hidden.
  • showowner: Boolean, true/false, if true, the parent listing is shown with the event.
  • uselistingicon: Boolean, true/false, if true, the listing icon is used instead of the default one for the event type.
  • refreshurl: A special URL that retro.directory can call to update the number of places/tickets. See Automatic Ticket/Places Counter.
  • social: An object of links to social media. See Social Media Links for more information.

Response: HTTP 200 OK
[ "id": 123, "lat" : 51.477928, "lng" : -0.001545 ]
Fields:
  • id: The new Unique ID of this event
  • lat: If lookupaddress was set to true, this is the new geographic latitude
  • lng: If lookupaddress was set to true, this is the new geographic longitude

Get Event
Description: Fetches all the details about a specific event.
cURL Example:
Command:
curl -X GET -i https://retro.directory/api/v1/listing/<listing id>/event/<event id> -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK
{ "id": 110, "name": "Event Name", "description": "Event Description", "info": "Further Event Information", "type": 10, "start": "2023-04-11", "end": "2023-04-11", "url": "https://website", "bookingurl": "https://website/booking", "telephone": "+01 234567897", "address": "10 Retro Street, Retroshire", "postcode": "02832", "country": "GB", "lat": 51.477928, "lng": -0.001545, "places": 25, "showplaces": true, "onlineonly": false, "showowner": true, "uselistingicon": true, "refreshurl": "", "social": { "fb": "https://facebook.com/facebookgroup" } }
Fields:
  • id: The Unique ID of this event
  • name: The event title
  • description: The event description
  • info: Further information about the event.
  • type: The event type, see event types for a list
  • start: The event start date, in yyyy-mm-dd format
  • end: The event end date, in yyyy-mm-dd format
  • url: A website URL with more information about the event
  • bookingurl: A website URL that takes you directly to ticket purchases
  • telephone: Contact telephone number for more information
  • address: Address for the event
  • postcode: Postal / Zip code for the event address
  • country: Event address country as an ISO 3166 Alpha-2 Code country code.
  • lat: Geographic latitude of the event (for the map)
  • lng: Geographic longitude of the event (for the map)
  • places: Number of tickets/places available. 0=Sold out
  • showplaces: Boolean, true/false, if the number of tickets/places should be displayed.
  • onlineonly: Boolean, true/false, if true, the event is virtual/online - address/map is hidden.
  • showowner: Boolean, true/false, if true, the parent listing is shown with the event.
  • uselistingicon: Boolean, true/false, if true, the listing icon is used instead of the default one for the event type.
  • refreshurl: A special URL that retro.directory can call to update the number of places/tickets. See Automatic Ticket/Places Counter.
  • social: An object of links to social media. See Social Media Links for more information.


Update Event
Description: Updates the details for a specific event. All fields will be overwritten, even if omitted.
cURL Example:
Command:
Save to update.json:
{ "name": "Revised Event Name", "description": "Revised Event Description", "info": "Further Revised Event Information", "type": 10, "start": "2023-06-19", "end": "2023-10-01", "url": "https://website/revised", "bookingurl": "https://website/booking/revised", "telephone": "+11 234567897", "address": "20 Retro Street, Retroshire", "postcode": "02832", "country": "GB", "lat": 51.477928, "lng": -0.001545, "lookupaddress": true, "places": 20, "showplaces": true, "onlineonly": false, "showowner": true, "uselistingicon": true, "refreshurl": "", "social": { "fb": "https://facebook.com/facebookgroup" } }
curl -X PUT -i https://retro.directory/api/v1/listing/<listing id>/event/<event id> -H "Authorization: bearer <api-key>" -d @update.json
Fields:
  • name: The event title
  • description: The event description
  • info: Further information about the event.
  • type: The event type, see event types for a list
  • start: The event start date, in yyyy-mm-dd format
  • end: The event end date, in yyyy-mm-dd format
  • url: A website URL with more information about the event
  • bookingurl: A website URL that takes you directly to ticket purchases
  • telephone: Contact telephone number for more information
  • address: Address for the event
  • postcode: Postal / Zip code for the event address
  • country: Event address country as an ISO 3166 Alpha-2 Code country code.
  • lat: Geographic latitude of the event (for the map)
  • lng: Geographic longitude of the event (for the map)
  • lookupaddress: Boolean, true/false. If true, latitude and longitude will be looked up (Geocoding) using the address
  • places: Number of tickets/places available. 0=Sold out
  • showplaces: Boolean, true/false, if the number of tickets/places should be displayed.
  • onlineonly: Boolean, true/false, if true, the event is virtual/online - address/map is hidden.
  • showowner: Boolean, true/false, if true, the parent listing is shown with the event.
  • uselistingicon: Boolean, true/false, if true, the listing icon is used instead of the default one for the event type.
  • refreshurl: A special URL that retro.directory can call to update the number of places/tickets. See Automatic Ticket/Places Counter.
  • social: An object of links to social media. See Social Media Links for more information.

Response: HTTP 200 OK
[ "id": 123, "lat" : 51.477928, "lng" : -0.001545 ]
Fields:
  • id: The Unique ID of this event
  • lat: If lookupaddress was set to true, this is the new geographic latitude
  • lng: If lookupaddress was set to true, this is the new geographic longitude

Partially Update Event
Description: Updates only the supplied details for an event. Any field not present is left unaltered. This can be useful to update minor details such as the number of places.
cURL Example:
Command:
Save to update.json:
{ "name": "Revised Event Name", "description": "Revised Event Description", "info": "Further Revised Event Information", "type": 10, "start": "2023-06-19", "end": "2023-10-01", "url": "https://website/revised", "bookingurl": "https://website/booking/revised", "telephone": "+11 234567897", "address": "20 Retro Street, Retroshire", "postcode": "02832", "country": "GB", "lat": 51.477928, "lng": -0.001545, "lookupaddress": true, "places": 20, "showplaces": true, "onlineonly": false, "showowner": true, "uselistingicon": true, "refreshurl": "", "social": { "fb": "https://facebook.com/facebookgroup" } }
curl -X PATCH -i https://retro.directory/api/v1/listing/<listing id>/event/<event id> -H "Authorization: bearer <api-key>" -H "Content-Type: application/json" -d @update.json
Fields:
  • name: The event title
  • description: The event description
  • info: Further information about the event.
  • type: The event type, see event types for a list
  • start: The event start date, in yyyy-mm-dd format
  • end: The event end date, in yyyy-mm-dd format
  • url: A website URL with more information about the event
  • bookingurl: A website URL that takes you directly to ticket purchases
  • telephone: Contact telephone number for more information
  • address: Address for the event
  • postcode: Postal / Zip code for the event address
  • country: Event address country as an ISO 3166 Alpha-2 Code country code.
  • lat: Geographic latitude of the event (for the map)
  • lng: Geographic longitude of the event (for the map)
  • lookupaddress: Boolean, true/false. If true, latitude and longitude will be looked up (Geocoding) using the address
  • places: Number of tickets/places available. 0=Sold out
  • showplaces: Boolean, true/false, if the number of tickets/places should be displayed.
  • onlineonly: Boolean, true/false, if true, the event is virtual/online - address/map is hidden.
  • showowner: Boolean, true/false, if true, the parent listing is shown with the event.
  • uselistingicon: Boolean, true/false, if true, the listing icon is used instead of the default one for the event type.
  • refreshurl: A special URL that retro.directory can call to update the number of places/tickets. See Automatic Ticket/Places Counter.
  • social: An object of links to social media. See Social Media Links for more information.

Response: HTTP 200 OK
[ "id": 123, "lat" : 51.477928, "lng" : -0.001545 ]
Fields:
  • id: The Unique ID of this event
  • lat: If lookupaddress was set to true, this is the new geographic latitude
  • lng: If lookupaddress was set to true, this is the new geographic longitude


 cURL Example of Updating Places Only:
Command:
Save to patch.json:
{ "places": 12 }
curl -X PATCH -i https://retro.directory/api/v1/listing/<listing id>/event/<event id> -H "Authorization: bearer <api-key>" -H "Content-Type: application/json" -d @patch.json
Fields:
  • places: Number of tickets/places available. 0=Sold out

Response: HTTP 200 OK
[ "id": 123, ]
Fields:
  • id: The Unique ID of this event

Delete Event
Description: Delete an event from a listing. This cannot be undone.
cURL Example:
Command:
curl -X DELETE -i https://retro.directory/api/v1/listing/<listing id>/event/<event id> -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK
Followed by binary image data

Download Event Icon
Description: Downloads the currently used event icon, if one exists
cURL Example:
Command:
curl -X GET -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/icon -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK

Upload Event Icon
Description: Upload a graphic to be used as an icon for this event.
If uselistingicon is enabled, it will automatically be set to false.
Images can be JPEG, PNG, ICO, GIF, WEBP or BMP
Images will be resized to 32x32 pixels (maintaining aspect ratio).
cURL Example:
Command:
curl -X PUT -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/icon -H "Authorization: bearer <api-key>" --data-binary @icon.png
Response: HTTP 200 OK

Delete Event Icon
Description: Deletes any upload icon chosen for this event.
Once deleted the event icon will revert to the default icon for the type of event specified.
cURL Example:
Command:
curl -X DELETE -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/icon -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK

Download Event Banner
Description: Downloads the currently used event banner, if one exists
cURL Example:
Command:
curl -X GET -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/banner -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK

Upload Event Banner
Description: Upload a graphic to be used as a horizontal banner at the top of the event.
Images can be JPEG, PNG, GIF, WEBP or BMP
Images will be resized to 800x250 pixels by first:
  1. Resizing the image width to 800 pixels
  2. If taller than 256 pixels, cropping the image from the centre 250 pixels high

We recommend you upload images 800 pixels wide, and upto 250 pixels high and they will not be adjusted.
cURL Example:
Command:
curl -X PUT -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/banner -H "Authorization: bearer <api-key>" --data-binary @banner.jpg
Response: HTTP 200 OK

Delete Event Banner
Description: Deletes any upload banner image chosen for this event.
cURL Example:
Command:
curl -X DELETE -i https://retro.directory/api/v1/listing/<listing id>/event/<event id>/banner -H "Authorization: bearer <api-key>"
Response: HTTP 200 OK

API Home API Commands HTTP Errors Event Type IDs Social Media Links Auto Ticket/Places Refresh API Key Management