Events

Events happening in a municipality

Things are happening in any city or town, and this API is a way to have them managed in apps and websites.

The Event object

  {
    "id": "ev_c9988dea",
    "department_id": 4,
    "person_id": 7,
    "categories": ["ec_hsjh4445", "ec_1545pphh"],
    "name": "Town board meeting", 
    "description": "Town board meeting description",
    "status": "public", 
    "starts_at": "2022-07-08T10:00:00.000Z", // UTC datetime 
    "ends_at": "2022-07-08T14:00:00.000Z", // UTC datetime
    "starts_at_local": "2022-07-08T10:00:00.000Z", // jurisdiction timezone date 
    "ends_at_local": "2022-07-08T14:00:00.000Z", // jurisdiction timezone date
    "type": "recurrent", 
    "recurrence": {
      "frequency": "monthly",
      "interval": 1,
      "ends_on": "2024-07-06T08:22:57.000Z",
      "ends_after": 5,
      "on_different_date": true, 
      "every": "first", 
      "day_in_week": 3,
    }, 
    "metadata": null, 
    "source_event": null, 
    "image_url":"https://files.heygov.com/heyville.org/events/ev_c9988dea/image.jpg", 
    "venues": ["vn_abc123", "vn_knksd544"], 
    "source": "me_abc123",
    "location": {
      "lat": 44.8341639,
      "lng": -87.3770419,
      "address": "Sturgeon Bay, WI 54235, USA",
      "state": "WI",
      "country": "US"
    },  
    "created_at": "2022-07-06T08:22:57.000Z", 
    "updated_at": "2022-07-06T08:22:57.000Z" 
  }

Endpoints

List events for a municipality

GET https://api.heygov.com/{jurisdiction_id}/events

Path Parameters

Name	Type	Description
jurisdiction_id*	String	The ID for the municipality

Query Parameters

Name	Type	Description
limit	Number	How many events to return. Default: 50
month	String	Query for events happening in this month, prev month & next month, in YYYY-MM format (2023-05)
date_start	String	Query for events starting from this date (inclusive), in YYYY-MM-DD format
date_end	Sring	Query for events ending before this date (inclusive), in YYYY-MM-DD format
date_start_utc	String	Query for events starting from this date (inclusive), in YYYY-MM-DD format, UTC time
date_end_utc	String	Query for events ending before this date (inclusive), in YYYY-MM-DD format, UTC time
q	String	Search query for event name
page	Number	What page of results query to return Default: 1
type	String	Query events for their type, available types: single - one-off event recurrent - source recurrent event recurrence - sub-events created by a recurrent event
expand	String	Expand object data in returned list of events, options: parent - expand event type recurrence with source recurrent parent event, department person
category_id	String	Query events for category id
status	String	Query events for status, options: public private deleted
day	String	Query for events happening on this day, in YYYY-MM-DD format

200: OK List of events

Get single event

GET https://api.heygov.com/{jurisdiction_id}/events/{id}

Get detailed event

Path Parameters

Name	Type	Description
jurisdiction_id	String	The ID for the municipality
id	String	The event ID

200: OK Single event

// Single event object 
// GET https://api.heygov.com/{jurisdiction_id}/events/{id}
{
    "id": "ev_c9988dea", 
    "jurisdiction_id": "ju_1234abcd",
    "department_id": 4,
    "person_id": 7,
    "categories": ["ec_abcd1234", "ec_abcd7899"],
    "name": "Town board meeting", 
    "description": "Town board meeting description",
    "status": "public",
    "starts_at_local": "2022-07-08T03:00:00.000Z", 
    "ends_at_local": "2022-07-08T07:00:00.000Z",
    "starts_at": "2022-07-08T10:00:00.000Z",
    "ends_at": "2022-07-08T14:00:00.000Z", 
    "type": "single",  
    "recurrence": { 
    "frequency": "no"
    },  
    "metadata": null, 
    "source_event": null, 
    "location": null, 
    "image_url": null, 
    "created_at": "2022-07-06T08:22:57.000Z",
    "updated_at": "2022-07-06T08:22:57.000Z"
}

// Recurrence parent event object 
// GET https://api.heygov.com/{jurisdiction_id}/events/{uuid}
{
    "id": "ev_c9988dea",
    "jurisdiction_id": "ju_1234abcd",
    "department_id": 4,
    "person_id": 7,
    "categories": ["ec_shdjs554", "ec_hd4541ll"],
    "name": "Town board meeting",
    "description": "Town board meeting description",
    "status": "public",
    "starts_at_local": "2022-07-08T03:00:00.000Z",
    "ends_at_local": "2022-07-08T07:00:00.000Z",
    "starts_at": "2022-07-08T10:00:00.000Z",
    "ends_at": "2022-07-08T14:00:00.000Z",
    "type": "recurrent",
    "recurrence": {
        "frequency": "daily", 
        "interval": 1, 
        "ends_on": "2024-07-08T14:00:00.000Z"
    }, 
    "metadata": null, 
    "source_event": null,
    "image_url": null,
    "location": {
        "lat": 44.8341639,
        "lng": -87.3770419,
        "address": "Sturgeon Bay, WI 54235, USA",
        "state": "WI",
        "country": "US"
    }, 
    "created_at": "2022-07-06T08:22:57.000Z",
    "updated_at": "2022-07-06T08:22:57.000Z"
}

// Weekly recurrence object example 
{
...
    "recurrence": {
        "frequency": "weekly", 
        "interval": 1, // 1, 2, 3, ... max value 6 
        "ends_after": 10, 
        "day_in_week": 0 // value 0,1,2,3,4,5,6 for each day in the week
    }
...
}

// Monthly recurrence object example 
{
...
    "recurrence": {
        "frequency": "monthly", 
        "interval": 1, // 1,2,3, ... max value 6 
        "ends_after": 12, // Event occurrence
        "on_different_date": false
    }
...
}

// Monthly recurrence object example 
{
...
    "recurrence": {
        "frequency": "monthly", string 
        "interval": 1, number // value 1, 2, 3, ... max value 6 
        "ends_on": "2024-07-08T14:00:00.000Z",  datetime object or date string // if null, sets the value to two years from event start date
        "on_different_date": true, boolean // value true, false 
        "every": "first", string // time sequence every first, second, third, fourth, last 
        "day_in_week": 0 number // value 0,1,2,3,4,5,6 for each day in the week
    }
...
}

// Recurrence child event object
{
    "id": "ev_c9988dea",
    "jurisdiction_id": "ju-1234abcd", 
    "department_id": 4,
    "person_id": 7,
    "name": "Town board meeting",
    "description": "Town board meeting description", 
    "status": "public", 
    "starts_at_local": "2022-07-08T03:00:00.000Z",
    "ends_at_local": "2022-07-08T07:00:00.000Z",
    "starts_at": "2022-07-08T10:00:00.000Z",
    "ends_at": "2022-07-08T14:00:00.000Z",
    "type": "recurrence",
    "recurrence": null, 
    "metadata": null, 
    "source_event": "ev_6f99800b",
    "image_url": null, 
    "location": null, 
    "created_at": "2022-07-06T08:22:57.000Z",
    "updated_at": "2022-07-06T08:22:57.000Z"
}

404: Not Found

Create event

POST https://api.heygov.com/{jurisdiction_id}/events

Create new event

Request Body

Name	Type	Description
name*	String	Event name
starts_at*	Datetime	UTC datetime in format "YYYY-MM-DD HH:mm:ss"
ends_at*	Datetime	UTC datetime in format "YYYY-MM-DD HH:mm:ss"
starts_at_local	Datetime	Jurisdiction timezone datetime in format "YYYY-MM-DD HH:mm:ss"
ends_at_local	Datetime	Jurisdiction timezone datetime in format "YYYY-MM-DD HH:mm:ss"
status	String	Default: public
categories	Object	Default: null
venues	Object	Default: null
recurrence	Object

201: Created

// single event
fetch('https://api.heygov.com/heyville.org/events', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		"department_id": 4,
		"categories": ['evc_hsjh4445', 'evc_1545pphh'], 
		"venues": ["vn_abc123", "vn_kjn1212"],
		"name": "Special board meeting", 
		"status": "private",
		"image_url": "https://www.heyville.org/wp-content/uploads/2022/05/nyvq2juw4_o.jpg",
		"starts_at_local": "2023-02-08 11:00:00",
		"ends_at_local": "2023-02-08 16:00:00", 
		"recurrence": null
	})

})

// recurrent event
 fetch('https://api.heygov.com/heyville.org/events', {
         method: 'POST',
         headers: {
                 'Content-Type': 'application/json'
         },
         body: JSON.stringify({
                 "name": "Town board meeting",
                 "description": "Town board meeting description", 
                 "status": "public",
                 "image_url": "https://www.heyville.org/wp-content/uploads/2022/05/nyvq2juw4_o.jpg",
                 "starts_at_local": "2023-02-09 11:00:00",
                 "ends_at_local": "2023-02-09 16:00:00",
                 "recurrence": {
                    "frequency": "weekly", // Values: daily, weekly, monthly, yearly 
                    "interval": 1, 
                    "on_different_date": false
                 }
         })
})

400: Bad Request Some of the field values to create an event are invalid

Update single event

PUT https://api.heygov.com/{jurisdiction_id}/events/{id}

Update existing event data

Path Parameters

Name	Type	Description
jurisdiction_id	String	The ID for the municipality
id	String	The event ID

Request Body

Name	Type	Description
name	String	The event name
description	String	The event description

200: OK

// Update single event start datetime & end datetime example

fetch('https://api.heygov.com/heyville.org/events/{uuid}', {
	method: 'PUT',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
	    	"name": "Town board meeting", 
		"starts_at_local": "2023-02-09 11:00:00",
		"ends_at_local": "2023-02-09 16:00:00",
	    	"type": "single"
	})
})

// Update recurrent event
// Passing parent event {uuid} in order to update full recurrence sequence
fetch('https://api.heygov.com/heyville.org/events/{uuid}', {
	method: 'PUT',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
	  	"status": "deleted", 
	        "name": "Town board meeting updated"
	})
})

404: Not Found Event not found

400: Bad Request Event validation error, some field is invalid

Delete event

DELETE https://api.heygov.com/{jurisdiction_id}/events/{id}

Fully and irreversibly delete a event with connected image _url

Path Parameters

Name	Type	Description
jurisidction_id	String	The ID of municipality
id	String	The event ID

202: Accepted

404: Not Found

Upload image

POST https://api.heygov.com/{jurisdiction_id}/events/{id}/image

Upload event image

Path Parameters

Name	Type	Description
jurisdiction_id	String	The municipality ID
id	String	The event ID

Request Body

Name	Type	Description
file*	Binary

200: OK

Delete image

DELETE https://api.heygov.com/{jurisdiction_id}/events/id

Delete image from event

Path Parameters

Name	Type	Description
jurisidction_id	String	The municipality ID
id	String	The event ID

200: OK