MyCityScene API

By using our API, you (and any company or organization you may represent) understand, accept and agree to be bound by the API Terms of Use: https://mycityscene.com/about/api-terms-of-use

Overview ¶

Request URL: https://mycityscene.com/rest/v2

All requests have to contain the special header with yout API Key.

Header

x-api-key: ’YOUR-APPLICATION-TOKEN’

You can obtain your personal API Key here. It is available for Enterprise users only.

Some requests require users’ Authentication Tokens. Those tokens used to determine which user account will be used in the request. For example, your application has to use user’s Authentication Token on the event creating process to determine who will be the owner of the created event.

Every user can obtain his Authentication Token on his profile page.

HTTP response codes

All API methods will respond with one of the following HTTP response codes:

Code	Description
200	OK - Your request was successful and the response body contains a JSON representation
204	OK - No response. Your request was successful and MCS had no data to return to you
400	Bad Request - The data given in the request failed validation. Inspect the response body for details
403	Unauthorized - MCS failed to authenticate your request
404	Not Found - The specified method / resource could not be found
405	Method Not Allowed – The GET/POST/DELETE/PUT Method you input is not supported for this path
500	Server Error - This usually means there was a problem on MCS’s end. Double check to make sure your data sent is correct then reach out to MCS for help.

When MCS detects an error in your request, we will respond with a 400 (Bad Request) HTTP response and return a JSON error object:

Property	Type	Description
code	string	Code of the error: AuthenticationRequired, AccessDenied, NotFound, BadRequest, MethodNotAllowed
message	string	A detailed error message of what went wrong

States ¶

State Collection ¶

List All US States
GET`/state`

Example URI

GET /state

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id":2,
        "title":"Arizona",
        "short_title":"AZ"
    },
    ...
]

Areas ¶

Area Collection ¶

List All Areas
GET`/area`

Example URI

GET /area

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id":1,
        "state_id":10,
        "title":"Port Townsend & Jefferson County",
        "description":"In addition to its natural scenery ..."
    },
    ...
]

Communities ¶

Community Collection ¶

List All Communities
GET`/community`

Example URI

GET /community

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id":1,
        "area_id":1,
        "title":"Port Townsend",
        "timezone":"America/Los_Angeles"
    },
    ...
]

Venues ¶

Venue Collection ¶

List All Registered Venues
GET`/venue`

Example URI

GET /venue

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 209,
    "community_id": 23,
    "title": "Crook County Fairgrounds",
    "address": "SE Fairgrnds Access Rd",
    "city": "Prineville",
    "zip": "97754",
    "full_address": "SE Fairgrnds Access Rd, Prineville, OR 97754, USA",
    "latitude": 44.2915075,
    "longitude": -120.843062,
    "editable": true
  }
]

Venue Creation ¶

Create New Venue
POST`/venue`

You may create your own venue using this action. It takes JSON object.

title (required, string) - the title of the venue
address (required, string)
city (required, string)
zip (required, string) - the post code
community_id (required, integer) - the ID of the community of the venue
latitude (double) - latitude of the venue
longitude (double) - longitude of the venue

Example URI

POST /venue

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
  "community_id": 23,
  "title": "Crook County Fairgrounds",
  "address": "SE Fairgrnds Access Rd",
  "city": "Prineville",
  "zip": "97754",
  "latitude": 44.2915075,
  "longitude": -120.843062
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 412
}

Venue Updating ¶

Update a Venue
POST`/venue/{id}`

Your application can update the venues made by itselves only.

title (required, string) - the title of the venue
address (required, string)
city (required, string)
zip (required, string) - the post code
community_id (required, integer) - the ID of the community of the venue
latitude (double) - latitude of the venue
longitude (double) - longitude of the venue

Example URI

POST /venue/id

URI Parameters

HideShow

id: integer (required)
the unique ID of the venue

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
  "community_id": 23,
  "title": "Crook County Fairgrounds",
  "address": "SE Fairgrnds Access Rd",
  "city": "Prineville",
  "zip": "97754",
  "latitude": 44.2915075,
  "longitude": -120.843062
}

Response 204

Categories ¶

Public Category Collection ¶

List All available public Categories
GET`/category`

Example URI

GET /category

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 1,
        "title": "Live Music",
        "hashtags":"#livemusic #band",
    },
    ...
]

Private Category Collection ¶

To get all private categories of the user, you have to add a parameter token with an Authentication Token of the user.

List private categories of user
GET`/category?token={token}`

Example URI

GET /category?token='565ea878bb'

URI Parameters

HideShow

token: string (required) Example: '565ea878bb'
Authentication Token of category owner

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 56,
        "title": "My Personal Category",
        "hashtags":"#livemusic #band",
    },
    ...
]

Private Category Creation ¶

Create New Private Category
POST`/category`

You may create private categories for users using this action. It takes JSON object.

token (required, string) - Authentication Token of the category owner
title (required, string) - the title of the category
hashtags (optional, string) - space-separated hashtags

Example URI

POST /category

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
  "token": "a8757c87de7",
  "title": "Best Movies",
  "hashtags": "#cinema #movie"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 75
}

Category Updating ¶

Update a Private Category
POST`/category/{id}`

Your application can update the venues made by your account only.

token (required, string) - Authentication Token of the category owner
title (required, string) - the title of the category
hashtags (required, string) - space-separated hashtags

Example URI

POST /category/75

URI Parameters

HideShow

id: integer (required) Example: 75
the unique ID of the category

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
  "token": "a8757c87de7",
  "title": "Best Movies",
  "hashtags": "#cinema #movie"
}

Response 204

Events ¶

Event Collection ¶

List Your Events
GET`/event?token={token}`

Your application can get all events made by user.

Example URI

GET /event?token='565ea878bb'

URI Parameters

HideShow

token: string (required) Example: '565ea878bb'
Authentication Token of events owner

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    {
        "id": 4191,
        "venue_id": 141,
        "title": "Ambassador Meeting @ Manresa Castle",
        "description": "<p>Come join ...</p>" // html friendly
        "ticketing_url": "http://some.site/page/1/2/3",
        "more_info_url": "http://some.site/page/1/2/3-more",
        "facebook_url": "https://facebook.com/6354635432743524/",
        "image_url": "https://mcs.life/u/1234545444.jpg",
        "color": "#34A95B",

        // is Family Friendly?
        "is_all_ages": 1, // 1 or 0

        // is free event?
        "is_free": 0, // 1 or 0

        // is 21+ ?
        "is_21": 1, // 1 or 0

        // status can be on of: 'draft', 'on_review', 'approved', 'declined', 'unverified'
        "status": "on_review",

        "categories" : "2,3,17,24",

        // interval of the first time of event
        "start_at": "2017-06-17 17:00:00", // in timezone od the related community
        "end_at": "2017-06-17 23:00:00", // in timezone od the related community

        "rec_frequency": "monthly", // recurring event
        "rec_interval": 3, // every 3 months
        "rec_days_of_week": "[2,4]"
        "rec_repeat_by": "day_of_month",
        "rec_end_rule": "on",
        "rec_repeats": 0,
        "rec_end_on": "2020-01-01",

        "sessions": "" // comma separated date and time like "2017-08-12 10:00:00,2017-08-14 10:00:00"
    },
    ...
]

Event Creation ¶

Create New Event
POST`/event`

You may create your own event using this action. It takes JSON object.

token (required, string) - Authentication Token of the event owner
venue_id (required, integer) - the ID of related venue
title (required, string, max:255)
description (required, string, max:65000) - HTML of the description
ticketing_url (optional, string, max:255)
more_info_url (optional, string, max:255)
facebook_url (optional, string, max:255)
color (optional, string, max:32) - color for calendar widgets (example: ‘#ff58A0’)
is_all_ages (optional, integer) - possible values 1 or 0, default: 0
is_free (optional, integer) - possible values 1 or 0, default: 0
is_21 (optional, integer) - possible values 1 or 0, default: 0
image_url (optional, string) - the URL of the event image
categories (required, string, comma separated integers) - the list of the related categories
start_at (required, string) - the beginning of the first time of event in the timezone of related community. Format: ‘YYYY-MM-DD HH:MM:SS’
end_at (required, string) - the ending of the first time of event in the timezone of related community. Format: ‘YYYY-MM-DD HH:MM:SS’
rec_frequency (optional, string) - recurring mode. Possible one of: ‘none’, ‘daily’, ‘weekly’, ‘monthly’, ‘annually’, ‘sessions’. Default ‘none’.
rec_interval (optional, number) - recurring interval. Required for reccuring modes only.
rec_days_of_week (optional, string, comma separaed integers) - days of week (0-sunday, 1-monday, …). Used for ‘weekly’ mode only
rec_repeat_by (optional, string) - repeating mode. Possible one of ‘day_of_month’, ‘day_of_week’. Required for ‘monthly’ mode only
rec_end_rule (optional, string) - the rule of repeat ending. Possible on of ‘never’, ‘on’, ‘after’. Required for reccuring modes only.
rec_repeats (optional, integer) - the number of the repeating. Required for ‘after’ rule only.
rec_end_on (optional, string) - the date of the ending of the repeating. Format: “YYYY-MM-DD”. Required for ‘on’ rule only.
sessions (optional, string, comma separated dates) - the list of the beginning times of the sessions in timezone of the related community. Format “YYYY-MM-DD HH:MM:SS”. Required for ‘session’ mode only. Wrong values will be ignored.

Example URI

POST /event

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
    "token": "a8757c87de7",
    "venue_id": 141,
    "title": "Ambassador Meeting @ Manresa Castle",
    "description": "<p>Come join ...</p>",
    "ticketing_url": "http://some.site/page/1/2/3",
    "image_url": "http://my.supersite.com/images/123.jpg",
    "categories": "1,2,3,25",

    "start_at": "2017-10-17 17:00:00", // in timezone of the related community
    "end_at": "2017-10-17 23:00:00", // in timezone of the related community

    "rec_frequency": "session", // recurring event
    "sessions": "2017-10-19 17:00:00,2017-10-21 17:00:00,2017-10-25 19:30:00"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "id": 8412
}

Event Updating ¶

Update an Event
POST`/event/{id}`

token (required, string) - Authentication Token of the event owner
venue_id (required, integer) - the ID of related venue
title (required, string, max:255)
description (required, string, max:65000) - HTML of the description
ticketing_url (optional, string, max:255)
more_info_url (optional, string, max:255)
facebook_url (optional, string, max:255)
color (optional, string, max:32) - color for calendar widgets (example: ‘#ff58A0’)
is_all_ages (optional, integer) - possible values 1 or 0, default: 0
is_free (optional, integer) - possible values 1 or 0, default: 0
is_21 (optional, integer) - possible values 1 or 0, default: 0
image_url (optiona, string) - the URL of the event image
categories (required, string, comma separated integers) - the list of the related categories
start_at (required, string) - the beginning of the first time of event in the timezone of related community. Format: ‘YYYY-MM-DD HH:MM:SS’
end_at (required, string) - the ending of the first time of event in the timezone of related community. Format: ‘YYYY-MM-DD HH:MM:SS’
rec_frequency (required, string) - recurring mode. Possible one of: ‘none’, ‘daily’, ‘weekly’, ‘monthly’, ‘annually’, ‘sessions’. Default ‘none’.
rec_interval (optional, number) - recurring interval. Required for reccuring modes only.
rec_days_of_week (optional, string, comma separaed integers) - days of week (0-sunday, 1-monday, …). Used for ‘weekly’ mode only
rec_repeat_by (optional, string) - repeating mode. Possible one of ‘day_of_month’, ‘day_of_week’. Required for ‘monthly’ mode only
rec_end_rule (optional, string) - the rule of repeat ending. Possible on of ‘never’, ‘on’, ‘after’. Required for reccuring modes only.
rec_repeats (optional, integer) - the number of the repeating. Required for ‘after’ rule only.
rec_end_on (optional, string) - the date of the ending of the repeating. Format: “YYYY-MM-DD”. Required for ‘on’ rule only.
sessions (optional, string, cooma separated dates) - the list of the beginning times of the sessions in timezone of the related community. Format “YYYY-MM-DD HH:MM:SS”. Required for ‘session’ mode only. Wrong values will be ignored.

Example URI

POST /event/12

URI Parameters

HideShow

id: integer (required) Example: 12
the unique ID of the event

Request

HideShow

Headers

Content-Type: multipart/form-data

Body

{
    "token": "a8757c87de7",
    "venue_id": 141,
    "title": "Ambassador Meeting @ Manresa Castle",
    "description": "<p>Come join ...</p>",
    "ticketing_url": "http://some.site/page/1/2/3",
    "image_url": "http://my.supersite.com/images/123.jpg",
    "categories": "1,2,3,25",

    // interval of the first time of event
    "start_at": "2017-10-17 17:00:00", // in timezone of the related community
    "end_at": "2017-10-17 23:00:00", // in timezone of the related community

    "rec_frequency": "session", // recurring event
    "sessions": "2017-10-19 17:00:00,2017-10-21 17:00:00,2017-10-25 19:30:00"
}

Response 204

Overview ¶

Header ¶

HTTP response codes ¶

States ¶

State Collection ¶

List All US StatesGET/state

Example URI

Headers

Body

Areas ¶

Area Collection ¶

List All AreasGET/area

Example URI

Headers

Body

Communities ¶

Community Collection ¶

List All CommunitiesGET/community

Example URI

Headers

Body

Venues ¶

Venue Collection ¶

List All Registered VenuesGET/venue

Example URI

Headers

Body

Venue Creation ¶

Create New VenuePOST/venue

Example URI

Headers

Body

Headers

Body

Venue Updating ¶

Update a VenuePOST/venue/{id}

Example URI

Headers

Body

Categories ¶

Public Category Collection ¶

List All available public CategoriesGET/category

Example URI

Headers

Body

Private Category Collection ¶

List private categories of userGET/category?token={token}

Example URI

Headers

Body

Private Category Creation ¶

Create New Private CategoryPOST/category

Example URI

Headers

Body

Headers

Body

Category Updating ¶

Update a Private CategoryPOST/category/{id}

Example URI

Headers

Body

Events ¶

Event Collection ¶

List Your EventsGET/event?token={token}

Example URI

Headers

Body

Event Creation ¶

Create New EventPOST/event

Example URI

Headers

Body

Headers

Body

Event Updating ¶

Update an EventPOST/event/{id}

Example URI

Headers

Body

Header

HTTP response codes

List All US States
GET`/state`

List All Areas
GET`/area`

List All Communities
GET`/community`

List All Registered Venues
GET`/venue`

Create New Venue
POST`/venue`

Update a Venue
POST`/venue/{id}`

List All available public Categories
GET`/category`

List private categories of user
GET`/category?token={token}`

Create New Private Category
POST`/category`

Update a Private Category
POST`/category/{id}`

List Your Events
GET`/event?token={token}`

Create New Event
POST`/event`

Update an Event
POST`/event/{id}`