Airtable has an official guide for creating iCal feeds. You should use the iCal subscription link in the URL field when adding a Calendar to PlaceCal.

This generates an iCal feed, so see iCal (generic) for more information on how PlaceCal handles iCal sources.

Partners are the organisations and groups whose information is included on a PlaceCal site. They might be grassroots activist groups, those running a community space or venue, unincorporated community groups, housing associations, tenants’ groups, or other groups who organise events and meetings to benefit the social, cultural and emotional lives of everyone in the community.

Districts are a geographical boundary which PlaceCal uses to work out which PlaceCal sites a Partner should appear on. PlaceCal uses data from the UK census office to determine these boundaries, retrieved in 2019. There are currently no plans to update these boundaries when they change.

Districts are the second-smallest jurisdiction PlaceCal is configured to handle (after Wards) and usually refers to an area the size of a town or small city. In bigger cities like London, Districts relate to boroughs.

To import events from an Outlook 365 calendar PlaceCal needs its iCal/.ics link. This should be entered in the URL field when adding a Calendar to PlaceCal.

To find an Outlook 365 calendar's iCal/.ics link, go to the Calendar publishing section of the Outlook Calendar Options.

This generates an iCal feed, so see iCal (generic) for more information on how PlaceCal handles iCal sources.

Site admins are Users who have permission to edit the information which appears on a given PlaceCal site. This includes defining what it's called, editing and adding images and text on the public-facing homepage, and configuring certain settings about how information displays.

Site admins are usually also Organisers.

Neighbourhoods are a geographical region in PlaceCal (e.g. District or Ward).

PlaceCal sites which are place-based can be referred to as Neighbourhood sites. These sites are formed around a place-based community. They include everything within a specific geographical region, so are often quite narrowly focused (e.g. a single District). They usually include a much broader range of events than partnership sites, because the only criteria for inclusion is geographical location.

Root users are able to edit everything in PlaceCal. This account type is only held by members of the PlaceCal team.

If there's anything you expect to be able to amend, and can't, a User with a Root account should be able to resolve this for you.

Google Calendar is the default calendar associated with Google accounts. If you have a Gmail address, you have a Google calendar! You can access it by going to calendar.google.com.

To import events from a Google calendar PlaceCal needs the Public address in iCal format. This should be entered in the URL field when adding a Calendar to PlaceCal.

You can find the Public address in iCal format on each Google calendar's Settings page under the subheading Integrate calendar. Note that the calendar needs to be set to Make available to public in order for PlaceCal to be able to access its events.

Instructions on setting up a Google Calendar can be found in Google's official documentation.

This generates an iCal feed, so see iCal (generic) for more information on how PlaceCal handles iCal sources.

If you don't have a PlaceCal account and would like one, either get in touch with the Organiser of your community's PlaceCal site (contact information is displayed on the homepage of the site), or get in touch with the PlaceCal team if you'd like to bring PlaceCal to a new community.

To log in to PlaceCal navigate to admin.placecal.org and enter your credentials. These will be the email address and password you used to register with PlaceCal.

If you forget your password you can click 'Forgot password' to send an email with a link to reset it. If you're not sure which email is associated with your account, get in touch with the PlaceCal team.

There is also a link to log in at the very bottom of the PlaceCal homepage.

JSON-LD (sometimes referred to as Linked Data) is a way of conveying which many ticketing and events platforms use on their websites. , and PlaceCal can use it to import events.

To find if a site is using JSON-LD:

1. Navigate to a source you'd like to import into PlaceCal

2. Open the Inspector to view the webpage's code

3. Search for the string ld+json

If ld+json is present, it means there is structured data on the site which PlaceCal should be able to read (provided they're using the right fields, see below).

Information PlaceCal imports from JSON-LD sources

In the below list, the names of the relevant fields in JSON-LD which PlaceCal looks for are listed in square brackets.

• Unique ID [url]

• Event title [name]

• Description [description]

• Start date and time [start_date]

• End date and time [end_date]

• Address [location.address]

Note that the generic JSON-LD importer does not import URL or online address information.

Ticketsolve is a legacy importer which has not been tested since upgrades have been made to PlaceCal. If you are a Partner who would like to use a Ticketsolve source please be prepared for bugs, and be ready to .

Information PlaceCal imports from Ticketsolve

• Unique ID

• Event title

• Description

• Start time

• If the event has tickets available

• URL

Organisers are the people who support Partners and Partner admins. They are volunteers or community development workers who make connections with prospective partners and help them put all of the information about their organisation into PlaceCal. Organisers can create Partners in PlaceCal, create Partner admin accounts, and are available for support. They will usually be someone who is embedded in the community that the PlaceCal site serves, who most people using PlaceCal in that community will know.

You might see occasional references to or . They’re both types of Organiser, and you don’t need to worry about the difference if you’re not a PlaceCal developer. Organisers are usually also .

PlaceCal supports importing events directly from Dice venue pages.

Sample URL: https://dice.fm/venue/lido-9dan

You can paste venue URLs into the URL field when to PlaceCal. It should auto-detect the Dice link and import the events automatically.

Dice.fm uses JSON-LD, so see for more information on how PlaceCal handles JSON-LD sources.

Two types of RA calendar can be imported: promoters and clubs. To import them all you need is the URL of the promoter or club itself.

• Promoter URLs look like this:

• Club URLs look like this:

Note that some clubs are also promoters with the same name, make sure you pick the one most suitable.

iCloud Calendar is the default calendar associated with iCloud accounts. If you have an iCloud account (which you do if you use any Apple devices) you have an iCloud calendar!

You can access iCloud calendars using Apple's default Calendar app, which is installed by default on most Apple devices.

To import events from an iCloud calendar, PlaceCal needs the calendar's share link which begins webcal://. This should be entered in the URL field when to PlaceCal.

To get the calendar's share URL on a Macbook or iMac, find the name of the calendar you'd like to share in the list of calendars on the left of the Calendar app. If there's no list of calendars, click the button with the icon of a calendar at the top left to show them. You should then right click on the name of the calendar you'd like to share, and choose Share calendar from the menu. In the pop-up, check the box labelled Public calendar. Navigate away from the menu and then right click on the calendar again. You should now see an option labelled Copy URL to Clipboard. Choose this option, and paste it into the URL field when to PlaceCal.

If you don't see the option to Copy URL to Clipboard try choosing the option labelled Sharing Settings. This should display the URL beginning webcal:// which you can then highlight and copy.

This generates an iCal feed, so see for more information on how PlaceCal handles iCal sources.

Partner admins are the people who update information directly in PlaceCal on behalf of a Partner. These are the people who have direct contact with the Organiser of the PlaceCal Site they’re a part of.

To become a Partner admin, a User's PlaceCal account needs to be associated with a Partner. You can check the Partner admins for any given Partner on the page.

If you would like to become a Partner admin and add your group or organisation's activity to PlaceCal, either get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your community's PlaceCal site) or .

PlaceCal supports importing events directly from OutSavvy organiser URLs.

Sample URL: https://www.outsavvy.com/organiser/sappho-events

You can paste OutSavvy URLs into the URL field when to PlaceCal. It should auto-detect the OutSavvy link and import the organiser's events automatically.

Outsavvy uses JSON-LD, so see for more information on how PlaceCal handles JSON-LD sources.

PlaceCal is a community calendar software designed to work with communities to have greater visibility and agency over their events and information. It works through PlaceCal Organisers embedded in communities who connect grassroots groups, organisations and social initiatives (which we refer to as Partners) with PlaceCal, building on the tools they're already using.

PlaceCal is designed to reduce the admin burden on Partners by pulling information from places it's already being published, working with common calendar and ticketing platforms to stay up to date. It increases access and visibility of community activity by presenting event and Partner information in a clear format which doesn't require a login and is sorted chronologically. PlaceCal is designed to make it as easy and quick as possible to find out what's happening in your community, while resisting the capture and funneling of community infrastructure into big tech walled gardens.

PlaceCal is developed and maintained by Geeks for Social Change and Place Health Technology CIC, largely focusing on communities based in the UK (for now).

Using this documentation

This documentation has been collated to support Partner admins or Organisers in using PlaceCal. It also provides an overview as to how the software works for those who aren't yet working with PlaceCal, but are interested in using it in their community.

If you'd like to start using PlaceCal in your community, get in touch, or check our list of existing PlaceCal sites to see if there's already one where you are.

For developers of other software interested on integrating with PlaceCal, there is also a section on using the PlaceCal API.

Definitions of key terminology used in PlaceCal can be found in the Glossary.

Neighbourhood admins are Users who manage a Neighbourhood in PlaceCal. They will usually also be Site admins.

Users with root access are able to add new PlaceCal sites. If you don't have root access, you'll need to talk to the PlaceCal team.

To add a new site click the Add New Site button. This can be found at the top of the Sites page.

If you can't see the Add New Site button, you may not have the correct account permissions.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or contact the PlaceCal team.

When you click Add New Site you will be brought to the Create a new Site page. This has the same fields as found on the Configure a Site page.

To add a User either click the Add New User button at the top of the Dashboard or the Add new partner admin button under Connected entities on a Partner's settings page. Depending on your account permissions, you may not be able to add a new User.

Ideally all Partners will have a Partner admin, someone who can act on behalf of that Partner who has access to PlaceCal in order to edit and update information about said Partner. If a Partner admin is not present, the Partner's information can be edited by the PlaceCal Organiser who added them.

The only mandatory field on the New User page is their email address. When saved, this will send an email to the address entered with a link to set up their own PlaceCal User account.

Depending on the permissions your account has, you will be able to associate the new User with Partners, Neighbourhoods, Partnerships and/or a Role. Fields will appear blank if you are not able to edit them.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or contact the PlaceCal team.

Partners

Start typing the name of a partner you'd like to let this User edit and choose it from the drop-down list. On saving, this User will be added as Partner admin for any Partners entered here.

Neighbourhoods

Start typing the Neighbourhood you'd like to let this User manage and choose it from the drop-down list. On saving, this User will be added as Neighbourhood admin for any Neighbourhoods entered here.

Partnerships

Start typing the Partnership you'd like to let this User manage and choose it from the drop-down list. On saving, this User will be added as Partnership admin for any Partnerships entered here.

Role

Choose what level of permissions this account should have.

Adding Organisers

Organisers require a specific set of permissions in order to be able to administrate the PlaceCal sites they are responsible for.

Organiser permissions should include the Neighbourhood covered by their site, and any Partnership tags relevant to the specific site. They should have the Role of Citizen.

Unless they specifically manage a Partner, they don't need to have individual Partners associated with their account.

Calendars are event calendars run by Partners, which PlaceCal uses to import event listings to PlaceCal sites. Calendars are powered by a partner’s existing event management software such as Google Calendar, Outlook 365, or Eventbrite (there’s a full list of things we support under Supported Calendar sources). PlaceCal can work with most calendars that produce computer-readable event data.

Calendars are associated with Partners, and information about events which has been imported from a Calendar is displayed on a Partner's public-facing PlaceCal page.

PlaceCal can import events created using the default Squarespace events block. Squarespace has official documentation on adding events to your Squarespace site.

PlaceCal can import events using the default Squarespace URL of sites which have an events block. If you're using the default Squarespace URL, simply navigate to your events page and copy the page URL. You should then enter this URL in the URL field when adding a Calendar to PlaceCal.

Custom domain names do not work with PlaceCal. If you have a custom domain associated with your Squarespace site, you can still import your events by using the slug from your site in combination with your default Squarespace URL.

The slug is the part of a URL after and including the /.

To import events from a Squarespace site using a custom domain, navigate to the events page of your site and copy the slug (usually something like /events). Paste this somewhere you can refer to it later. Then find the default Squarespace site URL (usually something like https://bumblebee-raspberry-5hgh.squarespace.com). You now want to combine the two to make one URL by putting the slug at the end of your default Squarespace site URL (in this example, making https://bumblebee-raspberry-5hgh.squarespace.com/events). You should enter this combined URL in the URL field when adding a Calendar to PlaceCal.

Information PlaceCal imports from Squarespace

• Unique ID

• Event title

• Description

• Start date and time

• End date and time

• URL

A note on how Squarespace handles location information

Squarespace stores location information as latitude and longitude rather than as a street address, which means that this isn't able to be understood and matched to a street address by the PlaceCal importer. If you want to use Squarespace as a source, you will need to use Default location, No location or Online only when setting up the Calendar. This means Squarespace isn't a suitable source for a Partner which operates out of multiple physical locations, and we would recommend using an iCal source instead.

Partnerships are a specific type of PlaceCal site (e.g. trans-dimension.placecal.org) which are formed around an interest-based community. They’re more specific than a place-based or Neighbourhood site and might be something like ‘all of the trans-led and trans-involving events in this area’ or ‘all of the experimental music events in this region’.

The glossary contains definitions of key terms used throughout PlaceCal and this documentation.

• Calendars

• Districts

• Events

• Neighbourhoods

• Organisers

• Partners

• Partnerships

• Wards

• Sites

User roles

• Neighbourhood admins

• Partner admins

• Partnership admins

• Root

• Site admins

Partnership admins are Users who manage a Partnership in PlaceCal. They will usually also be Site admins.

User roles are the types of account PlaceCal uses. This section defines these roles as well as their permissions in PlaceCal.

Wards are a geographical boundary which PlaceCal uses to work out which PlaceCal sites a Partner should appear on. PlaceCal uses data from the UK census office to determine these boundaries, retrieved in 2019. There are currently no plans to update these boundaries when they change.

Wards are the smallest jurisdiction PlaceCal is configured to handle and relates to the electoral wards used in local elections in the UK.

PlaceCal supports importing events directly from Meetup URLs.

Sample URL: https://www.meetup.com/qas-agile-learning-culture-meetup-group

You can paste Meetup URLs into the URL field when adding a calendar to PlaceCal. It should auto-detect the Meetup link and import the Meetup group's events automatically.

Information PlaceCal imports from Meetup

• Unique ID

• Event title

• Description

• Start time and date

• End time and date (calculated by adding the event duration to the start date)

• Address

• URL

• Online address (if it's an online event)

Sites are individual PlaceCal instances (likehulme.placecal.org) which community members use to find event and Partner information. Each site shows information about the PlaceCal neighbourhood or partnership including the contact information for that community’s Organiser. Sites can come in a few different flavours – we originally split them strictly between place-based (Neighbourhoods) and interest-based (Partnerships) but as PlaceCal has evolved this distinction has become less useful.

PlaceCal is able to import the events from an organiser page on Eventbrite. You can do this by using the organisation's profile URL in the URL field when adding a calendar to PlaceCal.

You might need to add an Organisation to your Eventbrite account to get this URL. Eventbrite has tutorials for this.

Information PlaceCal imports from Eventbrite

PlaceCal pulls the following from Eventbrite events:

• Unique ID

• Event title

• Description

• Start date and time

• End date and time

• Address

• URL

• Online address (if an online event)

By default PlaceCal supports and data sources. PlaceCal also supports specific ticketing and event platforms which provide an API for integrations. These are listed below. Instructions for setting up a calendar feed which PlaceCal can import can be found by clicking through on the source you would like to use.

List of supported sources

• (RA)

Sources PlaceCal doesn't support

Google Sheets

We can’t meaningfully import . There are various Google Sheets to iCal integrations which you're welcome to try but we can’t offer specific support to these as they are constant moving targets.

Facebook

Facebook have closed their APIs and make it practically impossible to scrape public data. If you’re extremely brave you can try to improve our abandoned but again, we can’t support with this.

Fatsoma

Fatsoma don't provide a suitable API or metadata output.

Sources PlaceCal could support with additional resources

TicketTailor

TicketTailor have an API PlaceCal could use, with support to develop the importer.

iCal is a widely-used standard for publishing calendar and event data which PlaceCal can use as a source. We provide instructions on connecting , , and calendars, but you might have iCal data from another source which PlaceCal can still read!

To identify an iCal source look for the .ics file extension. This will appear at the end of any iCal file, which means it will also show up in valid iCal URLs.

Most calendar software will support exporting an .ics file of a given calendar. This file can then be hosted online. As long as it's hosted somewhere where the URL isn't going to change (meaning whenever it's updated, it needs to be replaced with a file of exactly the same name with the same path to get to it) you can use this URL as a source for PlaceCal when .

We provide information about common services which handle this part for you because for most people this will be the easiest and most convenient way to host an .ics file, but you're free to use whichever hosting works for you.

Information PlaceCal imports from iCal sources

• Unique ID

• Event title

• Description

• Start date and time

• End date and time

• Address

• URL

• Online address (if an online event)

Events are a key part of how PlaceCal functions. Event data is imported into PlaceCal and displayed on Partner pages and PlaceCal sites.

Events are automatically displayed on PlaceCal sites. Events will show on sites when:

• The event’s Calendar belongs to a Partner who is shown on that site.

• The event’s address is within a Neighbourhood that is shown on that site (and it’s a ).

• The event’s address matches the name and postcode of a Partner who is shown on that site.

Events can be connected to Partners in two ways:

• They are automatically connected to the Partner the Calendar belongs to. This Partner is shown on an event as being the Event organiser.

• They will be optionally connected to a Partner if they have the Partner’s name and postcode saved in their address, and if that Partner has consented to . By default, Partners will not have event matching enabled, but Partners can opt into this by ticking this Can be assigned events box in the . Events will only be matched to Partners whose name is found in the events’ address, who have the same postcode as the event, and have consented to event matching.

To add a Calendar, click the Add New Calendar button. This can be found on the Calendars page of the admin interface, or at the top of the Dashboard.

If you can't see the Add New Calendar button, you may not have the correct account permissions.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or contact the PlaceCal team.

When you click Add New Calendar you will be brought to the Create a new Calendar page. This is where you can configure the calendar as well as associate it with an existing Partner. It is mandatory to associate a Calendar with a Partner, so you might need to add a Partner first.

Details

Partner Organiser

Choose a Partner from the dropdown list to associate with this Calendar. This Calendar will then be used as a source of information for the selected Partner's PlaceCal events.

Partners can have multiple associated Calendars.

Name

This should be a human-readable name which accurately describes this Calendar. This is most useful for differentiating between Calendars where a partner has more than one source of event information, for example both Eventbrite and Google Calendar.

URL

This is where to put the URL of the calendar feed you'd like PlaceCal to import. PlaceCal supports a number of different types of calendars and calendar feeds. PlaceCal will periodically check for new events on the source calendar located at this URL and import them to PlaceCal.

Each Calendar can only have one URL.

Importer mode

The Importer mode tells PlaceCal how to handle the URL you've given it. For most cases it'll do a good enough job working this out on its own—but if you get an error this is a good place to check.

If you're using an .ics feed from a source that we don't specifically list, make sure you choose Generic iCal / .ics from the dropdown.

Location

Default location

Set the default location for this Calendar here, by choosing a Partner from the dropdown. Note that only Partners with a set street address will appear in this list.

Where should location information for this Calendar come from?

This determines how the location information for each event is handled by PlaceCal. You should choose the option which most closely reflects how the Calendar is used by the Partner—for example a Calendar which never usually has address information because all of the events happen in the same place should be set to either Default location or Event where possible. A Calendar for a Partner which never operates from the same place twice should be set to Event.

• Event where possible: Use the address from each event. If the address is invalid or it doesn't have one, use the calendar's default location.

• Event: Use the address from each event. If an address is invalid or it doesn't have one, the event will import with no location.

• Default location: Always use the calendar's default location.

• Room number: Get a room number from the event's address, and overwrite the rest of the address with the calendar's default location.

• No location: Discard any address information.

• Online only: Discard any address information but retain web links.

Public Contact Information

This information is used on the public event listing pages in the "Problem with this listing? Let us know." contact link at the bottom of the show event page. Providing this information isn't compulsory.

What next?

When you've filled out all of the relevant fields click Create Calendar to queue the Calendar for creation. If there are any errors or missing information you will be prompted to correct these fields, after which you'll need to click Create Calendar again to save the Calendar.

Once the Calendar has been successfully created PlaceCal will queue it for import. Events might take a few minutes to show on the associated Partner's page, and only events in the future will be imported by PlaceCal.

To add a Partner, click the Add New Partner button. This can be found on the Partners page of the admin interface, or at the top of the Dashboard.

If you can't see the Add New Partner button, you may not have the correct account permissions.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or contact the PlaceCal team.

When you click Add New Partner you will be brought to the New Partner page. This is where you can configure the basic information about a new Partner. This process has been simplified to capture the most important information first.

Basic Information

Name

Enter the name of the Partner. This will be the name which is displayed to the public, which will go live on any PlaceCal sites this Partner is associated with as soon as it is added. This should be a name which users of PlaceCal site(s) will be able to understand and recognise. It needs to be more than five characters long.

Place

Partners need to be associated with at least one place. This can be a fixed address if they usually operate from a fixed location, or a service area which can be a Ward or District. Keep this information as specific as possible – limited to where this partner actually runs events rather than the geographical spread of the people they are trying to reach.

Address

If the Partner has a street address where they operate from which is publicly accessible, add it here. If they don't have a fixed address, add a Service Area below.

Service Areas

Choose one or more Service Area(s) from the dropdown. These will usually be the general area the Partner organises events in. If the Partner only organises events in one Ward, try and use that rather than District level information to keep this field as specific and useful as possible. Depending on how the PlaceCal site is configured this will display as either a Ward or District badge in the list of Partners on each site this Partner appears on.

Once you've filled the name and either an Address or Service Area you will be able to save the Partner. Once you hit save, the Partner will appear on any PlaceCal Neighbourhood sites covering the area the Partner is based in.

Saving the Partner from the New Partner page will take you to the Edit Partner page, which is where you can add more information about the Partner (and edit previously submitted information).

Users with root access are able to add new Partnerships, which the PlaceCal interface handles as a Tag. If you don't have root access, you'll need to talk to the PlaceCal team.

To add a new Tag, click the Add New Tag button. This can be found at the top of the Tags page.

If you can't see the Add New Tag button, you may not have the correct account permissions.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or contact the PlaceCal team.

When you click Add new Tag you will be brought to the Create a New Tag page.

Basic information

Name

Enter the name of the tag

Slug

Enter the slug, which will be the URL where the tag is accessible. This should be all lowercase, with no spaces, using hyphens between words. Ideally it should be the same as the name of the tag, unless the name is very long.

Description

Enter a description of the tag

System tag

When adding Partnership tags, leave this box unchecked.

Type

Choose Category, Facility or Partnership. This cannot be edited once selected. You will likely not need to add Facility or Category tags.

Tagged Partners

Choose which Partners will be assigned this tag, if they already exist in PlaceCal.

Assigned Users

Choose which Users will have permission to assign this tag. Ensure you choose the Organiser of any site which will use this tag, if it's a Partnership tag.

Structured data is information which is understandable by computers. This means it is consistent—it’s in the same format every time, and that each piece of information is labelled with metadata which tells the computer both what it is and how it should be used. Unstructured data isn't consistent and doesn't have metadata. This means it's difficult for computers to understand and it's not possible to apply processes to it in order to reliably collect and use the information for other purposes.

We can conceptualise data in different dimensions, relating to how much structure it has (and how easy it is for both humans and computers to understand it):

1D data - Flyers, posters, and Instagram posts

1D data is data which is visually resolved, meaning you use visual information to pick up cues about how to use the data, for example an arrow on a map pointing to an address, or a transport icon next to the name of a station. It’s not standardised, and is often not searchable as text is baked into an image, or physically printed. Instagram posts are 1D data because they often use poster-style images with a lot of information in the image itself. 1D data is not easily usable – a human has to go through every piece of data individually and make it into a more computer-readable format to use it with a piece of software, like a calendar app.

2D data - Spreadsheets

2D data is visually resolved, but has some structure. Spreadsheets are 2D data because while you can apply formulas to them to get some functionality out of them, and they have column headings and titles telling you what each piece of data is, it’s down to a human to make sure all of the information in that column is appropriate and in the right format. It’s easy for spreadsheets to contain erroneous information, for example a date entered into a spreadsheet as 03/10 might be resolved as March 10th or October 3rd depending on how the spreadsheet is configured.

3D data - Database

3D data is able to be resolved visually and understood by a computer, meaning both humans and computers find it useful. 3D data is consistent and has checks stopping the wrong kind of information being entered. This is the most usable kind of data for working with software and integrating data into other places – it requires the least human oversight to work and keep working, and is least likely to introduce mistakes. This is the kind of data PlaceCal can work with!

What does structured data allow us to do?

Because structured data is computer-readable, we can use it to automate the import of event listings into PlaceCal. This reduces the administrative burden on Partners by removing the need to manually update PlaceCal listings on top of their usual event planning process—many community calendars which don't use PlaceCal are manually updated, often requiring a great deal of labour to keep up to date. If Partners are already using tools which output structured data, they only need to connect this to PlaceCal once to have their events listed on the Site.

PlaceCal also outputs structured data—each PlaceCal Site outputs an iCal feed which you can follow in any calendar software which allows you to subscribe to calendar feeds. PlaceCal also has an API which developers of other apps can use to integrate with information from PlaceCal.

Sites which use structured data (specifically JSON-LD) are also great for SEO—Google uses JSON-LD to inform its Rich Results, which is their term for the details they display about events in Search and Maps.

Popular formats

PlaceCal can read data from a variety of sources. Some common formats of structured data are:

iCal

iCal is a format for calendar events, which every reputable digital calendar is able to read and export. It outputs the data in a predictable way every time, which PlaceCal can read and use to output an events feed. It’s used by software like Microsoft Outlook and Google Calendar, so will probably be the type of feed a partner uses if the main way they keep track of their events is through a calendar software rather than a ticketing platform.

JSON-LD

JSON-LD is another format for structured data, which can support event data. It’s often used by SaaS (Software as a Service) web platforms like Squarespace, and might be used by ticketing providers too. It’s useful on the web because it’s the format that Google and other search engines use to find event information on a web page and surface that in search results.

APIs

These are custom ways of structuring data which are specified by the companies who make software. These are not standard across platforms, which means that to work with them you need to make your software understand the terms laid out by the API. Companies sometimes use an API if they want to restrict who can access their data – Facebook is a notable example. They have an API but restrict access, which means that independent software (like PlaceCal) can’t access their information, but big-budget companies like Ticketmaster can.

PlaceCal is a software in direct opposition to the capture and funneling of community infrastructure into big-tech walled-gardens. It works on a principle that communities should have agency over their own data, and understand how to get the most out of the tools we use to organise our communities without becoming complicit in the big-tech agenda.

In the current tech landscape, the tools which are most accessible are also often tools which come with a catch. Many sell your data to advertisers or to train AI models, or have punitive algorithms which can obscure or limit your reach unless you play into their games of regular posting and ultimately spending more and more time and energy on their platforms.

What are walled gardens?

Walled gardens are platforms and services which don't interoperate easily with software outside of their ecosystem. They usually require you to have an account and sign in with them to view the content on their platform, and might also require additionally becoming part of a specific channel or group on top of logging in. Walled gardens can also be referred to as silos, and are most associated with 'big tech' companies like Meta (Facebook, WhatsApp, Instagram), X, Apple, etc.

On top of requiring you to log in to see the content on their platform they will usually disincentivise linking out to other sites, sometimes algorithmically 'punishing' posts which encourage users to leave their platform. They're not interested in playing nicely with others, because they have an economic incentive to keep you reliant on their ecosystem (and bring all your friends along too) as this allows them to track your data and sell it to advertisers and for AI training.

Algorithms

A key way walled gardens function is through the use of algorithms to determine what users of their site see. Algorithms are employed to make it more addictive to use their platforms, pushing posts which are more divisive or 'engaging' to the feeds of their users. This doesn't work in the favour of groups who are simply trying to let people know about something happening in their neighbourhood—it pushes groups into using a platform daily to try and grow their reach on top of the thing they are on the platform to promote in the first place. This wastes time which could otherwise be spent planning and delivering services and creates a sense of disappointment when posts advertising events don't do as well as hoped. Algorithmic feeds also often surface days-old posts just at the wrong time, meaning potential attendees might not find out about an event until after it's happened.

PlaceCal resists this by using a non-algorithmic, chronological feed of upcoming events. Curation happens at the Partner level, through human connections fostered by PlaceCal Organisers. By showing all events by trusted Partners in chronological order, PlaceCal sites stay populated, relevant and local while resisting spam and avoiding the addictive properties of algorithmic feeds.

Accessibility issues around logging in

When information is on a walled garden platform, this means anyone who wants to know what's going on in a community has to sign up to the same walled garden. Logging in is a significant accessibility issue—ask any librarian. It's not a given that everyone who needs to access your community information will be able to keep track of email addresses, passwords, and 2FA. This also assumes that everyone in your community has access to their own personal computer or smartphone.

PlaceCal resolves this by generating a public-facing website which is accessible without logging in. This means anyone in a community can access their PlaceCal Site from any internet-connected device, regardless of if they own it, if it's a library machine, or if it's borrowed from a friend.

Tracking and surveillance

Walled gardens rely on the data they collect from users in order to make a profit. It's their incentive for the walled garden behaviour—they want to keep you on their platform as long as possible so they can extract as much data from you as possible. Ultimately, this goes against many of the goals of community organisers and means that even the most well-intentioned work is propping up the same hegemony we're trying to organise against.

Lack of agency over data

On top of the surveillance, relying on corporate platforms to maintain the infrastructure our communities are built on means that they're free to change how they operate at any time, which can scupper community communication. PlaceCal used to be able to pull data from Facebook, but they changed how their API works and now it can't. This has been a significant barrier for people using Facebook to organise events. Accounts are also subject to the terms of service on the platforms which host them, which be difficult to navigate when it's not possible to talk to a person about why an account has been suspended.

Cumulative impact

A cumulative effect of the shortfalls of walled gardens over time is a general sense of disillusionment with platforms and technology. PlaceCal is designed to combat this by demonstrating that it doesn't have to be like that—we have the tools we need to communicate about and within our communities without needing big tech companies to act as a mediator. This disillusionment however can be a significant obstacle PlaceCal Organisers face when onboarding Partners—many people simply don't want to give any more time to learning a new technology because the ones they've already used have broken their own usability promises.

Currently we only serve read queries and no mutations. The examples are written in javascript.

The following code is a bare-bones query wrapper using the node-fetch npm module.

import fetch from 'node-fetch';

const endPoint = 'http://192.168.0.39:3000/api/v1/graphql';

function query (query, variables) {
  return new Promise((resolve, reject) => {
    fetch(endPoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
      body: JSON.stringify({
        variables,
        query
      })
    })
    .then(r => r.json())
    .then(data => resolve(data))
  });
}

To configure a Partner you'll need to navigate to the Edit Partner page.

If you're in the process of adding a new Partner, you should end up on this page after you save a Partner for the first time. Otherwise, go to the Partners tab on the left hand side and choose the Partner you'd like to edit from the list which appears. Click on the name of the Partner to go to the Edit Partner page.

You can also get here from the Dashboard if you edited or added the Partner you'd like to edit recently.

Partner admins should be able to access and configure these settings using their own PlaceCal User account.

Some of the fields on this page might appear differently (or not appear at all) depending on the permissions your User account has. If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or .

Basic Information

This section is for basic information about a Partner which will be shown to the public on any PlaceCal sites this Partner appears on.

Name

This information is initially set on the New Partner page, as it's a key part of how PlaceCal operates. More information on how to configure these settings is on the page of this documentation.

Summary

This is a short description which should use one to two sentences (max) to describe what the Partner does. It should stick to the most important things someone might need to know about the Partner, for example a knitting group for women in Norwich who meet every month might set their summary to something like Monthly knitting group for women in Norwich to meet, knit, and natter!. This information is displayed in the list of Partners on any PlaceCal site this Partner appears on.

Description

This is space for a longer description which goes into more detail, which appears on the Partner's public PlaceCal page. The aforementioned knitting group might use this space to talk in more depth about the kinds of projects members usually bring, if there are supplies provided or if attendees should bring their own, and if they ever organise one-off events like craft fairs.

Accessibility Information

If a Partner has an accessibility statement they should paste it here.

We recommend Partners use this space to talk about the general accessibility of their events. If they are based in a fixed location, they should use this space to talk in detail about the accessibility of that location. This can be information about the physical details of the site (is there level access? If there are steps, how many? Are there accessible toilets on site?), logistics in accessing the site (nearest station and other public transport options, parking), if there is a separate quiet space, and any precautions the organisers have in place against transmission of airborne pathogens (if masks are required, if air filtration is present).

Geeks for Social Change created a guide for the (a PlaceCal site which highlights events by and for trans people) with Gendered Intelligence and the Greater Manchester Coalition of Disabled People called . It contains recommendations on things to consider when putting on events to include both trans and disabled people, as well as a questionnaire Partners can fill to generate a comprehensive accessibility statement.

Image

This image is used to illustrate the Partner's PlaceCal page. It should be something which represents the Partner, for example a logo (if they have one) or an image from one of their events.

Place

This information is initially set on the New Partner page, as it's a key part of how PlaceCal operates. More information on how to configure these settings is on the page of this documentation.

Online

These links will display on a Partner's public PlaceCal page if entered.

Website address

Add a web address for this Partner, if they have one. Enter the full address including https://.

Facebook link

Add a Facebook page for this Partner, if they have one. Enter the slug from this Partner's Facebook page (everything after the / in the URL).

Twitter handle

Add a Twitter handle for this Partner, if they have one. Enter the Partner's Twitter/X username.

Instagram handle

Add an Instagram handle for this Partner, if they have one. Enter the Partner's Instagram username.

Contact Information

Contact information is used both by PlaceCal staff and Organisers and the public who might need more information or to ask a question about an event or Partner. We ask for both public and private contact information where possible to cover these use cases.

Public Contact

Enter contact information the public can use to contact the Partner in the case that they need further information or have a question about events the Partner is sharing on PlaceCal. This information is visible on the Partner's public PlaceCal page.

Partnership Contact

If different from the public contact information, enter contact information that PlaceCal staff and Organisers can use to contact the Partner. This information is not visible on the Partner's public PlaceCal page.

Opening times

Set opening times for this Partner, if they have both a fixed location and regular opening times. These are displayed to the public so should be kept up-to-date where possible.

Tags

Facilities tags are used to highlight Partners which provide certain amenities. If you add a Facilities tag to your Partner, it will appear under that heading on the homepage of any PlaceCal site they appear on.

Categories tags appear in the filtering options when looking at the list of Partners on PlaceCal sites. They can be used to sort through the Partners on a site, which is useful for members of the public using PlaceCal to find events relevant to them. They can only be set at the Partner level, not on a per-event basis.

Partnership tags are used by PlaceCal staff and Organisers to add Partners to specific Partnerships. You might not see this field, depending on the permissions your User account has.

Event matching

Event matching is a way of connecting events to a PlaceCal Partner, even if they weren't originally uploaded to that Partner's PlaceCal Calendar(s). This can be useful when a Partner runs a space which other Partners operate out of, for example a large venue with multiple units occupied by Partners, which also runs its own events. Partners should check Can be assigned events if they want events from other Partners to be able to be matched to their address and appear on their PlaceCal Partner page.

This used to be PlaceCal's default behaviour, but has since been changed to an opt-in model. Partners who have been on PlaceCal since prior to Spring 2024 should check this setting is configured to their preference.

Connected entities

Calendars

This section should display any connected Calendars. Clicking the button Add a new calendar should take you to the page. If there is nothing in this section, this Partner is not currently importing any events to PlaceCal sites.

Partner admins

Partner admins are Users who have permission to edit this Partner's settings. Clicking the Add a new partner admin button will take you to the page.

If you're a Site admin you can configure the public-facing elements of a PlaceCal site, including what it's called, its description, cover image, as well as other settings about how PlaceCal functions and appears to the public by navigating to the Edit site page.

You can find the Edit Site page by clicking the Edit button under the site you'd like to edit, found under Your sites on your Dashboard. If you can't see anything under Your sites your account may not have site admin permissions.

If you think you should have different account permissions, get in touch with the Organiser of your PlaceCal site (contact information can be found on the homepage of your PlaceCal site) or .

Name

This field acts as the title of the calendar. It should be short and descriptive, for example 'PlaceCal Norwich' for a site or 'Climate Justice North East' for a site.

Place name

This field should be a descriptor for the geographical region the site covers. It should be as accurate and specific as possible, for example 'Norwich' for a site which only shows events in Norwich, or 'the UK' for a UK-wide Partnership site. It should be able to fit into this sentence: We're working with local organisations to create a calendar of everything going on in Place name.

Tagline

This is a short description (just a few words) which can appear with the name of the site. The default tagline for PlaceCal is The Community Calendar which you are welcome to retain, or customise to fit your site's needs.

URL

Depending on your account permissions, this field will likely not be editable. This is configured by the PlaceCal team when . This shows the URL which houses the public-facing PlaceCal site. This is the URL you should share when directing people to your PlaceCal Site.

Slug

Depending on your account permissions, this field will likely not be editable. This is configured by the PlaceCal team when .

Hero text

Up to 120 characters which will display over the image on the public-facing homepage of your PlaceCal site.

Description

A short description of your PlaceCal site which displays on the public-facing homepage. This should tell visitors in brief about what PlaceCal is and how it's used in your community.

Published

Check this box to advertise this site in this , accessible from . If this box is unchecked your site will not appear in public listings of PlaceCal sites.

Images

Theme

Choose a colour scheme for your PlaceCal site. This changes the accent colour of elements of your PlaceCal site's UI, for example the colour of links.

Logo

Upload a .svg or .png file to display in the top left of your PlaceCal site. This should be a simple image which represents your Site. When setting up a new site, the PlaceCal team will make a logo using your site's name, which should be uploaded here by default.

Logos should have no whitespace above and below them -- please crop to the exact height of the image or it'll look smaller than it should.

Footer logo

Upload a .svg or .png file to display in the footer of your PlaceCal site. This should be a simple image which represents your site. When setting up a new site, the PlaceCal team will make a logo using your site's name, which should be uploaded here by default.

Hero image

Upload a .jpg, .jpeg or .png file to display on the homepage of your PlaceCal site, and in the public listings on the PlaceCal homepage if your site is . This can be any image which represents your site.

Hero image credit

Enter the credit for whoever took your hero image. Please only use images you have permission to use, or which are in the public domain.

Hero alt-text

Enter suitable alt-text which describes the content of your hero image. Be accurate and concise.

Neighbourhood information

Depending on your account permissions you might not be able to edit all of the fields in this section. If you need to amend the information in fields which you're not able to directly edit, .

Main neighbourhood

This defines the area covered by your PlaceCal site. It should be as accurate and specific as possible. This is configured by the PlaceCal team when .

Neighbourhood information display

This setting tells PlaceCal how much detail to show on the list of Partners associated with your site. By default this is set to , but for sites which cover larger areas it might be useful to set this to display the .

Other neighbourhoods to include

This adds other geographical regions to your PlaceCal site. This can be particularly useful for sites which handle a lot of edge cases—groups based just on the other side of a jurisdictional boundary but which commonly serve the community served by the PlaceCal site.

Community Technology Partnerships (CTPs) are a concept we’ve been developing —a methodology for creating tools that work, with the communities they’re for. It means understanding and documenting the barriers facing the groups we work with, and using those barriers to determine the direction for any tools or processes we develop. We wrote more about it in our following receiving funding from the National Lottery Community Fund.

CTPs inform our approach to PlaceCal, rooted in the role of the . Organisers are key to making PlaceCal work—a point of contact, embedded in the community, building real relationships with and helping to develop their tools and processes in order to get the most out of PlaceCal (and the other tools they're already using).

The CTP methodology emerged from Asset-Based Community Development, pioneered by C2 (Connecting Communities). It works with the assets which are already in place in a community—the resources, skills and experience a community already has—and works with the community to better connect and use these assets.

In context

Applying Community Technology Partnerships to PlaceCal means that we aim to work with what people are already using and link that to PlaceCal. This is why PlaceCal works with a large range of —so there's the best chance possible that Partners who want their information on PlaceCal won't need to change much, if anything, about how they're currently working.

PlaceCal Organisers work directly with Partners to train Partner admins to use PlaceCal, and advise on how Partners can use the skills and tools they already have in-house to generate event information . They also serve as the bridge between the PlaceCal team and the communities on the ground PlaceCal is operating in. If you're interested in becoming a PlaceCal Organiser !

Digital skills and obstacles to using PlaceCal

Community Technology Partnerships also mean listening to the needs of the community as they present them. We found that digital skills confidence is a huge issue in many communities, so part of the work of implementing PlaceCal (for Organisers) is to help people in your community to build their digital skills. This might be something as simple as showing them how to use Google Forms and Google Calendar to keep track of their events, if they don’t have anything in place already they feel comfortable using.

Many groups, especially grassroots and DIY organisations, are working with fuzzy and indistinct systems for managing events internally, which doesn’t create a single point of truth—something that's just as frustrating for the people working on a project as it is difficult to import into PlaceCal. By working with a group to develop a system which works with PlaceCal, Organisers will also be addressing a social and organisational issue for that group, and making it easier for them to deliver their work on the ground.

If a group an Organiser is working with has a particularly hard time getting into PlaceCal—we want to know about it! We ask Organisers to keep a list of the barriers and obstacles faced by the partners they work with so we can feed this in to our ongoing research, informing the trajectory of PlaceCal’s development.

We go into more detail about how to support Partners in the New Organiser Onboarding training we offer to all PlaceCal Organisers. If you're interested in undertaking this training please .

Either specified by the query with these fields or returned from the server in this structure

PingType: String


NeighbourhoodType {
  name: String
  abbreviatedName: String
  unit: String
  unitName: String
  unitCodeKey: String
  unitCodeValue: String
}

ContactType {
  name: String
  email: String
  telephone: String
}

OpeningHoursType {
  dayOfWeek: String
  opens: String
  closes: String
}

AddressType {
  streetAddress: String
  postalCode: String
  addressLocality: String
  addressRegion: String
  neighbourhood: NeighbourhoodType
}

PartnerType {
  id: ID
  name: String
  summary: String
  description: String
  accessibilitySummary: String
  logo: String
  url: String
  facebookUrl: String
  twitterUrl: String
  address: AddressType
  areasServed: [NeighbourhoodType]
  contact: ContactType
  openingHours: OpeningHoursType
	articles: [Article]
}

EventType {
  id: ID
  name: String
  summary: String
  description: String
  startDate: ISO88601Format
  endDate: ISO88601Format
  address: AddressType
  organizer: PartnerType
}

ArticleType {
  name: String
  headline: String
  text: String
  articleBody: String
  datePublished: ISO88601Format
  dateCreated: ISO88601Format
  dateUpdated: ISO88601Format
  providers: [Partners]
}

For a very basic test the following code will ping the server:

The response will look something like:

Getting a list of Partners

A more useful example may be getting a list of partners:

At its heart the query looks like this. node lists the set of fields you want returned.

Response should be:

Show

let queryString = `
query Partner($id: ID!) { 
  partner(id: $id) {
    id
    name
    summary
    description
    accessibilitySummary
    logo
    url
    facebookUrl
    twitterUrl
    address {
      streetAddress
      postalCode
      addressLocality
      addressRegion
      neighbourhood {
        name
        abbreviatedName
        unit
        unitName
        unitCodeKey
        unitCodeValue
      }
    }
    contact {
      name
      email
      telephone
    }
    openingHours {
      dayOfWeek
      opens
      closes
    }
    areasServed {
      name
      abbreviatedName
      unit
      unitName
      unitCodeKey
      unitCodeValue
    }
  }
}`;

query(queryString, { id: 10 })
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  });

/* typical response */
{
  "data": {
    "partner": {
      "id": "10",
      "name": "London Partner",
      "summary": "A Partner in London",
      "description": "Longer description of London Partner is here",
      "accessibilitySummary": "",
      "logo": "",
      "url": "",
      "facebookUrl": "",
      "twitterUrl": "https://twitter.com/",
      "address": null,
      "contact": {
        "name": "Me",
        "email": "[email protected]",
        "telephone": ""
      },
      "openingHours": [],
      "areasServed": [
        {
          "name": "London",
          "abbreviatedName": null,
          "unit": "region",
          "unitName": "London",
          "unitCodeKey": "RGN19CD",
          "unitCodeValue": "E12000007"
        }
      ]
    }
  }
}

Index

Show a sample request returning all events for a given date range with a given partner and tag.

let queryString = `
  query PartnerConnection($first: Int, $after: String) { 
    partnerConnection(first: $first, after: $after) {
      pageInfo {
        hasNextPage
        endCursor
      }
      edges {
        cursor
        node {
          id
          name
          summary
          description
          accessibilitySummary
          logo
          url
          facebookUrl
          twitterUrl
          address {
            streetAddress
            postalCode
            addressLocality
            addressRegion
            neighbourhood {
              name
              abbreviatedName
              unit
              unitName
              unitCodeKey
              unitCodeValue
            }
          }
          contact {
            name
            email
            telephone
          }
          openingHours {
            dayOfWeek
            opens
            closes
          }
          areasServed {
            name
            abbreviatedName
            unit
            unitName
            unitCodeKey
            unitCodeValue
          }
        }
      }
    }
  }`;

/* 
The partnerConnection pagination works the same as event pagination above
*/

/* return the first block of partners */
query(queryString, {first: 3})
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  })

/* response */
{
  "data": {
    "partnerConnection": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "Mw"
      },
      "edges": [
        {
          "cursor": "MQ",
          "node": {
            "id": "12",
            "name": "Service Area Partner",
            "summary": "",
            "description": "",
            "accessibilitySummary": "",
            "logo": "",
            "url": "",
            "facebookUrl": "",
            "twitterUrl": "https://twitter.com/",
            "address": null,
            "contact": {
              "name": "Me",
              "email": "[email protected]",
              "telephone": ""
            },
            "openingHours": [],
            "areasServed": [
              {
                "name": "London",
                "abbreviatedName": null,
                "unit": "region",
                "unitName": "London",
                "unitCodeKey": "RGN19CD",
                "unitCodeValue": "E12000007"
              }
            ]
          }
        },
        {
          "cursor": "Mg",
          "node": {
            "id": "10",
            "name": "London Partner",
            "summary": "A Partner in London",
            "description": "Longer description of London Partner is here",
            "accessibilitySummary": "",
            "logo": "",
            "url": "",
            "facebookUrl": "",
            "twitterUrl": "https://twitter.com/",
            "address": null,
            "contact": {
              "name": "Me",
              "email": "[email protected]",
              "telephone": ""
            },
            "openingHours": [],
            "areasServed": [
              {
                "name": "London",
                "abbreviatedName": null,
                "unit": "region",
                "unitName": "London",
                "unitCodeKey": "RGN19CD",
                "unitCodeValue": "E12000007"
              }
            ]
          }
        },
        {
          "cursor": "Mw",
          "node": {
            "id": "13",
            "name": "Inner London Partner",
            "summary": "Summary of outer london partner",
            "description": "",
            "accessibilitySummary": "",
            "logo": "",
            "url": "",
            "facebookUrl": "",
            "twitterUrl": "https://twitter.com/",
            "address": null,
            "contact": {
              "name": "",
              "email": "",
              "telephone": ""
            },
            "openingHours": [
              {
                "dayOfWeek": "Monday",
                "opens": "09:00:00",
                "closes": "17:00:00"
              },
              {
                "dayOfWeek": "Tuesday",
                "opens": "09:00:00",
                "closes": "17:00:00"
              },
              {
                "dayOfWeek": "Friday",
                "opens": "09:00:00",
                "closes": "17:00:00"
              }
            ],
            "areasServed": [
              {
                "name": "Inner London",
                "abbreviatedName": null,
                "unit": "county",
                "unitName": "Inner London",
                "unitCodeKey": "CTY19CD",
                "unitCodeValue": "E13000001"
              }
            ]
          }
        }
      ]
    }
  }
}

Show

let queryString = `
  query Event($id: ID!) { 
    event(id: $id) { 
      id
      name
      summary
      description
      startDate
      endDate
      address {
        streetAddress
        postalCode
        addressLocality
        addressRegion
      }
      organizer {
        id
        name
      }
    }
  }`;

query(queryString, { id: 2 })
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  });

/* response */

{
  "data": {
    "event": {
      "id": "2",
      "name": "event 0: A summary of an event",
      "summary": "event 0: A summary of an event",
      "description": "A longer description of this event",
      "startDate": "2022-02-10 00:00:00 +0000",
      "endDate": null,
      "address": {
        "streetAddress": "123 A Street, A place",
        "postalCode": "SE2 0QG",
        "addressLocality": "Belvedere",
        "addressRegion": "London (region)"
      },
      "organizer": null
    }
  }
}

Index

Shows a set of events in manageable chunks. Can be used to load events on demand for pagination/infinite scroll. There is an explanation of how connections work in comments.

let queryString = `
  query EventConnection($first: Int, $after: String) { 
    eventConnection(first: $first, after: $after) {
      pageInfo {
        hasNextPage
				endCursor
      }
      edges {
        cursor
        node {
          id
          name
          summary
          description
          startDate
          endDate
          address {
            streetAddress
            postalCode
            addressLocality
            addressRegion
          }
          organizer {
            id
            name
          }
        }
      }
    }
  }`;

/* return the first block of events */
query(queryString, {first: 5})
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  });

/* first response */
"data": {
    "eventConnection": {
      "pageInfo": {
        "hasNextPage": true
      },
      "edges": [
        {
          "cursor": "MQ",
          "node": {
            "id": "2",
            "name": "event 0: A summary of an event",
            "summary": "event 0: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "Mg",
          "node": {
            "id": "3",
            "name": "event 1: A summary of an event",
            "summary": "event 1: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "Mw",
          "node": {
            "id": "4",
            "name": "event 2: A summary of an event",
            "summary": "event 2: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "NA",
          "node": {
            "id": "5",
            "name": "event 3: A summary of an event",
            "summary": "event 3: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "NQ",
          "node": {
            "id": "6",
            "name": "event 4: A summary of an event",
            "summary": "event 4: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        }
      ]
    }
  }
}

/*
Notes on connection pagination:
Cursors are GraphQL's way of identifying a record in a connection.
They act like IDs but are more complicated for reasons.

Input parameters
  first: limit the number of records to return
  after: only fetch records that follow on from this cursor

In the response each record is wrapped in an 'edge' that contains 
the GQL cursor identifier.

pageInfo:
  hasNextPage: (boolean) there are records that follow from this block
  endCursor: (string) the cursor of the last record retrieved 
*/

/* then to get the next block of events */
query(queryString, {first: 5, after: "NQ"})
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  });

/* second response */
{
  "data": {
    "eventConnection": {
      "pageInfo": {
        "hasNextPage": true
      },
      "edges": [
        {
          "cursor": "Ng",
          "node": {
            "id": "7",
            "name": "event 5: A summary of an event",
            "summary": "event 5: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "Nw",
          "node": {
            "id": "8",
            "name": "event 6: A summary of an event",
            "summary": "event 6: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "OA",
          "node": {
            "id": "9",
            "name": "event 7: A summary of an event",
            "summary": "event 7: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "OQ",
          "node": {
            "id": "10",
            "name": "event 8: A summary of an event",
            "summary": "event 8: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        },
        {
          "cursor": "MTA",
          "node": {
            "id": "11",
            "name": "event 9: A summary of an event",
            "summary": "event 9: A summary of an event",
            "description": "A longer description of this event",
            "startDate": "2022-02-10 00:00:00 +0000",
            "endDate": null,
            "address": {
              "streetAddress": "123 A Street, A place",
              "postalCode": "SE2 0QG",
              "addressLocality": "Belvedere",
              "addressRegion": "London (region)"
            },
            "organizer": null
          }
        }
      ]
    }
  }
}

Filter

Events can be filtered by date range, neighbourhood or tag. All events are returned in ascending order of start date.

let queryString = `
  query EventsByFilter(
    $fromDate: String, 
    $toDate: String, 
    $neighbourhoodId: Int, 
    $tagId: Int) 
  {

    eventsByFilter(
      fromDate: $fromDate, 
      toDate: $toDate, 
      neighbourhoodId: $neighbourhoodId, 
      tagId: $tagId) 
    { 
      id
      name
      summary
      description
      startDate
      endDate
      address {
        streetAddress
        postalCode
        addressLocality
        addressRegion
      }
      organizer {
        id
        name
      }
    }
  }`;

/* 
notes on event filter
The filter has the following parameters:
  fromDate: the initial start point. defaults to 
	  date request was made. can be in the past.
    format is YYYY-MM-DD HH:MM
  toDate: the end limit of query. must be after fromDate
  neighbourhoodId: scope events to be in a 
    neighbourhood. returns events in BOTH
    the address and service area.
  tagId: scope events to only one tag
*/

query(queryString)
  .then( (response) => {
    console.log(JSON.stringify(response, null, 2));
  });

/* response */
{
  "data": {
    "eventsByFilter": []
  }
}

Some sample GQL queries that show the various input fields. The fields can be combined in one query.

# default query with no args
query {
	eventsByFilter {
	   id
	   name
	   startDate
	}

# query with fromDate
query {
	eventsByFilter(fromDate: "1985-01-01 00:00") {
	   id
	   name
	   startDate
	}

# query with fromDate and toDate
query {
	eventsByFilter(fromDate: "1990-01-01 00:00", toDate: "1990-03-01 00:00") {
	  id
	  name
	  startDate
	}

# query with neighbourhoodId
query {
  eventsByFilter(neighbourhoodId: 123) {
    id
    name
  }
}

# query with tagId
query {
  eventsByFilter(tagId: #{have_tag.id}) {
    id
    name
  }
}