Home

CityGrid Advertising APIs

Skip to end of metadata
Go to start of metadata

Introduction

The CityGrid Places Management API is part of the Advertising by CityGrid suite of APIs which allows developers to retrieve, create and update places and the content associated with places.

Contents

Places Get Endpoint

The CityGrid Places Get API allows to retrieve information regarding places. Response formats include XML and JSON.   

Please note that Get API will require https and is a V3 endpoint. 

Request Parameters

Field

Type

Description

Required

Examples

external_place_ids

Comma separated listing if String values

A list of External IDs to be resolved to places

Required if no place_ids are specified

183765,
mar_biz6368

place_ids

Comma-separated list of Long values

List of places IDs 

Required as an alternate for external_place_id

11790182,12314

Get Header values

Name

Values

Description

Content-Type

Application/JSON
Application/XML

Return format. Content-Type and Accept must match

Accept

Application/JSON
Application/XML

Return format. Content-Type and Accept must match

authToken

Authentication Token from Places Management API

Required

Request Example

Description

Endpoint

Get Places by External Place IDs

api.citygridmedia.com/content/places/v3/get?external_place_ids=4320920_a,5320920_a

Response Parameters

Field

Type

Description

rval

Places Page

Place identified by the selector

Places Page

Field

Description

Type

place_id

The ID of the Place

Integer

place

The Place

Place

Place

Field

Parent Element

Description

Type

Notes

external_place_id

 

External Place ID

String

 

place_id CGM business listing IDLong 

primary_tag_id

 

Tag id for business' main category

Long

 

secondary_tags

 

Secondary tags ids for business' main category

String

Comma separated tag values

name

 

Name of the location

String

 

address_1

 

Storefront address

String

 

address_2

 

Delivery point

String

 

city

 

City of the location

String

 

state

 

State of the location

String

 

postal_code

 

Postal Code of the location

Long

 

phone_number

 

Phone number of the Location

String

 

display_url

 

Displayed URL of the location

String

 

website_url

 

Website URL of the location

String

 

tagline

 

Tagline of the location

String

 

menu_link

 

URL to a menu page

String

 

reservation_link

 

URL to a reservation page

String

 

owners_message

 

Message of the owner of the location

String

 

bullet_1

 

Advertorial bullet text

String

 

bullet_2

 

Advertorial bullet text

String

 

bullet_3

 

Advertorial bullet text

String

 

facebook_username

 

Facebook username of the location

String

 

twitter_handler

 

Twitter username of the location

String

 

image_path

 

Path of the image for the location

String

 

customer_message_url

 

Url of the customer message

String

 

business_hours

 

Hours of work of the location

String

 

suppress_phone

 

Do not publish business phone number

Boolean

 

suppress_address

 

Do not publish business address

Boolean

 

is_tracking_enabled

 

This value is deprecated (will default to 1)

Boolean

 

parking

 

 

String

 

expertise

 

 

String

 

insurance

 

Pertinent insurance information

String

 

license

 

Pertinent licenses held by the business

String

 

service_provider

 

Name of individual providing the service

String

 

mobile_number

 

 

String

 

tip_text

 

A tip from the business owner

String

 

tip_title

 

A tip from the business owner

String

 

Media Types Supported

Header

Type

Content Type

Application/JSON

 

Application/XML

Accept

Application/JSON

 

Application/XML

Response Examples

JSON Response
Error rendering macro 'code': Invalid value specified for parameter 'lang'
 {
  "totalNumEntries": 2,
  "places": [
    {
      "place_id": "605310021",
      "external_place_id": "4320920_a",
      "primary_tag_id": "921",
      "secondary_tags": "919",
      "name": "Springfield Community College",
      "address_1": "630 Stim St. #200",
      "address_2": "Suite B",
      "city": "Springfield",
      "state": "VA",
      "postal_code": "95814",
      "phone_number": "5559200157",
      "display_url": "SpringfieldCollege.com",
      "website_url": "http://ua1.ybsa.int:8080/trackingenginewebapp/tracking.html?MB_ID=43209",
      "tagline": "Bachelor and Master's degree programs designed just for you! Visit us today.",
      "menu_link": "",
      "reservation_link": "",
      "owners_message": "Serving the Region for over 30 years, the University Campus is located in downtown near the Capitol.",
      "bullet_1": "Bachelor and Master's Degrees",
      "bullet_2": "Serving the Region for 30 Years.",
      "bullet_3": "Evening/Day Classes.",
      "facebook_username": "Univrsity",
      "twitter_handle": "",
      "image_path": "",
      "customer_message_url": "",
      "business_hours": "Sun,Sat Closed Mon-Thu 9am-5pm Fri 9am-4:40pm",
      "suppress_phone": "1",
      "suppress_address": "1",
      "is_tracking_enabled": "1",
      "parking": "",
      "expertise": "",
      "insurance": "",
      "license": "",
      "service_provider": "",
      "mobile_number": "",
      "tip_text": "",
      "tip_title": "",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    },
    {
      "place_id": "605310023",
      "external_place_id": "5320920_a",
      "primary_tag_id": "921",
      "secondary_tags": "4193",
      "name": "Sylar Community College",
      "address_1": "5693  Rooster Rd",
      "address_2": "-",
      "city": "Orlando",
      "state": "FL",
      "postal_code": "32819",
      "phone_number": "5558779639",
      "display_url": "Our Schools",
      "website_url": "http://uatkopwrct01.ss.edu:8080/trackingenginewebapp/",
      "tagline": "Bachelor and Master's degree programs designed just for you! Visit us today.",
      "menu_link": "",
      "reservation_link": "",
      "owners_message": "Contact us to discuss your professional and academic goals.  Our Programs include: Organizational Behavior, Counseling and Psychology, Public Administration, Health Administration, Nursing, and Education.  We offer a complete university facility with, six classrooms, full service library, and professional meeting rooms.",
      "bullet_1": "BS and MS Degrees",
      "bullet_2": "Serving the Region for 30 Years.",
      "bullet_3": "Online Classes Available.",
      "facebook_username": "",
      "twitter_handle": "",
      "image_path": "",
      "customer_message_url": "",
      "business_hours": "Open 24 Hours",
      "suppress_phone": "1",
      "suppress_address": "1",
      "is_tracking_enabled": "1",
      "parking": "Parking in back.  Street parking in front.",
      "expertise": "",
      "insurance": "",
      "license": "",
      "service_provider": "",
      "mobile_number": "",
      "tip_text": "",
      "tip_title": "",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}
XML Response

Error Reporting

Parameter

Error Message

HTTP Header

"Unauthorized access, Must provide authToken in request header"

Selectors

"Incorrect request parameter."

Selectors

"Data not found."

placeId

"Place does not exist"

JSON Error Response (single place error, full request SUCCESS)
Error rendering macro 'code': Invalid value specified for parameter 'lang'
{
  "totalNumEntries": 2,
  "places": [
    {
      "place_id": "",
      "external_place_id": "xxx123",
      "primary_tag_id": "",
      "secondary_tags": "",
      "name": "",
      "address_1": "",
      "address_2": "",
      "city": "",
      "state": "",
      "postal_code": "",
      "phone_number": "",
      "display_url": "",
      "website_url": "",
      "tagline": "",
      "menu_link": "",
      "reservation_link": "",
      "owners_message": "",
      "bullet_1": "",
      "bullet_2": "",
      "bullet_3": "",
      "facebook_username": "",
      "twitter_handle": "",
      "image_path": "",
      "customer_message_url": "",
      "business_hours": "",
      "suppress_phone": "",
      "suppress_address": "",
      "is_tracking_enabled": "",
      "parking": "",
      "expertise": "",
      "insurance": "",
      "license": "",
      "service_provider": "",
      "mobile_number": "",
      "tip_text": "",
      "tip_title": "",
      "response": {
        "code": "ENTITY_NOT_FOUND",
        "message": "The place could not be found.",
        "field": ""
      }
    },
    {
      "place_id": "605310021",
      "external_place_id": "4320920_a",
      "primary_tag_id": "921",
      "secondary_tags": "919",
      "name": "Springfield Community College",
      "address_1": "630 Stim St. #200",
      "address_2": "7th Street",
      "city": "Springfield",
      "state": "VA",
      "postal_code": "95814",
      "phone_number": "5559200157",
      "display_url": "http://www.usa.edu/regions/",
      "website_url": "http://ua1.ybsa.int:8080/trackingenginewebapp/tracking.html?MB_ID=43209",
      "tagline": "Bachelor and Master's degree programs designed just for you! Visit us today.",
      "menu_link": "",
      "reservation_link": "",
      "owners_message": "Serving the Region for over 30 years, the University Campus is located in downtown near the Capitol.",
      "bullet_1": "Bachelor and Master's Degrees",
      "bullet_2": "Serving the Region for 30 Years.",
      "bullet_3": "Evening/Day Classes.",
      "facebook_username": "Univrsity",
      "twitter_handle": "",
      "image_path": "",
      "customer_message_url": "",
      "business_hours": "Sun,Sat Closed Mon-Thu 9am-5pm Fri 9am-4:40pm",
      "suppress_phone": "1",
      "suppress_address": "1",
      "is_tracking_enabled": "1",
      "parking": "",
      "expertise": "",
      "insurance": "",
      "license": "",
      "service_provider": "",
      "mobile_number": "",
      "tip_text": "",
      "tip_title": "",
      "response": {
        "code": "SUCCESS",
        "message": "Success",
        "field": ""
      }
    }
  ],
  "response": {
    "code": "SUCCESS",
    "message": "Success",
    "field": ""
  }
}


JSON Error Response (full request error)
XML Error Reponse

Places Mutate Endpoint

The places/mutate endpoint allows users to create and update places. The operation is invoked via HTTPS POST to:

Input data such as request parameters are subject to Places Management APIfield size limits.

Request Parameters

The mutate operations available on places are:

  • The ADD operator, which creates places.
  • The SET operator, which updates and removes place properties. Certain non-required content values are removed by providing zero-length strings as arguments to the SET operator.

Changes you submit to CityGrid places will go through an offline process where they will be matched against and possibly merged with existing CityGrid data.

Icon

When creating a new place, do not indicate a placeId. It is recommended to use an externalPlaceId to track your listings as the placeId returned by the ADD request may be eventually merged to an existing place. The externalPlaceId will remain consistent.

Every places/mutate request requires the following two parameters:

Property

Type

Description

Required

operator

{ADD, SET}

Type of operation to perform (case sensitive)

Yes

operand

Place

The place to operate on (may be virtual)

Yes

The properties of a place object in a request are:

Field

Description

Required

Type

Example

Limit

external_place_id

Your own ID for a place. Cannot be deleted. Used for referencing the place.

Required for SET. Strongly recommended for ADD.

String

183268
mar_biz133

255 chars

place_id

The ID of the place in the CityGrid ID space. Cannot be deleted.

Required for SET if external_place_id is not specified.

Long

 1231231

 

name

Place name. The keyword 'closed' should not be a part of the name. Cannot be deleted.

Required for ADD

String

 

255 chars

primary_tag_id

Tag id for the place's primary category. It is a single id and not a list. Cannot be deleted.

Required for ADD.

Long

123

 

secondary_tags

Secondary tag ids for the place as a comma separated list.

No

String

1727
123,456,8,11412

 

address_1

Storefront address. Cannot be deleted.

Required for ADD. Unless virtual flag is set up to "1"

String

 

128 chars

address_2

Address extension, such as a delivery point

No

String

Suite B
3rd Floor
APT 234

128 chars

city

City. Cannot be deleted.

Required for ADD. Unless virtual flag is set up to "1"

String

 

128 chars

state

Either a two-character state or province code or its full name. Currently case-sensitive. Cannot be deleted.

Required for ADD. Unless virtual flag is set up to "1"

String

CA
CALIFORNIA

40 chars

postal_code

Postal code. Cannot be deleted.

Required for ADD. Unless virtual flag is set up to "1"

String

91202

5 chars

phone_number

Phone number. Cannot be deleted.

Required for ADD. Unless virtual flag is set up to "1"

String

(123)456-7890
123-456-7890
1234567890
(123) 456-7890
0011234567890

60 chars

tagline

Place tagline

No

String

 

140 chars

website_url

URL of place website.

Only if display_url is present

String

 

2000 chars

display_url

How the place's URL should be displayed.

No

String

 

255 chars

menu_link

 

No

String

 

1000 chars

reservation_link

 

No

String

 

1000 chars

owners_message

 

No

String

 

4000 chars

bullet_1

 

No

String

 

75 chars

bullet_2

 

No

String

 

75 chars

bullet_3

 

No

String

 

75 chars

facebook_username

 

No

String

 

512 chars

twitter_handler

 

No

String

 

24 chars

image_path

URL of an image (1)

No

String

 

2000 chars

business_hours

 

No

String

 

255 chars

customer_message_url

 

No

String

 

1000 chars

suppress_phone

Whether the phone number should be suppressed on display (1=Yes, 0=No). Cannot be deleted.

No

{0, 1}

 

 

suppress_address

Whether the address should be suppressed on display (1=Yes, 0=No). Cannot be deleted.

No

{0, 1}

 

 

parking

 

No

String

 

64 chars

expertise

 

No

String

 

200 chars

insurance

 

No

String

 

2000 chars

license

 

No

String

 

2000 chars

service_provider

 

No

String

 

150 chars

mobile_number

 

No

String

 

10 chars

tip_text

Text for the place's tip. (2)

No

String

 

400 chars

tip_title

Title for the place's tip. (2)

No

String

 

40 chars

is_virtual

Whether the place is virtual.

No

{0, 1}

 

 

Notes

  • (2) The tip_text and tip_title properties must either both be present or both be absent.

Request Header Values

Header

Description

Required

Valid Values

Content-Type

Media type of the request body

Yes

application/json
application/xml

Accept

Requested format for the response

Yes

application/json
application/xml

authToken

Authentication Token from the Places Management API

Yes

Valid token

developerToken

The token received during registration

Yes

Valid token

 

Request Examples

Example 1: A JSON ADD Example
Icon

Postal codes are strings and must be enclosed in double quotes. JSON requests containing numeric (unquoted) values such as 90069 instead of "90069" will generate an error.

Example 2: A JSON SET Example
Example 3: A JSON Add Example for a Virtual Place
Example 3: An XML ADD Example
Example 4: An XML SET Example

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

place_id

Long

The ID of the created or updated place

Response Examples

Example 1: A JSON Response
Example 2: An XML Response
  • No labels