Places Management API

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.

Places Get Endpoint

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

https://api.citygrid.com/content/places/v3/get

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

Request Parameters

Field	Type	Description	Required	Examples

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

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

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

Field	Type	Description
rval	Places Page	Place identified by the selector

Places Page

Field	Description	Type

Field	Description	Type
place_id	The ID of the Place	Integer
place	The Place	Place

Place

Field	Parent Element	Description	Type	Notes

Field	Description	Type	Notes
external_place_id	External Place ID	String
place_id	CGM business listing ID	Long
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

Header	Type
Content Type	Application/JSON
	Application/XML
Accept	Application/JSON
	Application/XML

Response Examples

JSON Response

 {
  "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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<results>
<totalNumEntries>2</totalNumEntries>
<places>
	<place>
    	<place_id>605310021</place_id>
    	<external_place_id>4320920_a</external_place_id>
    	<primary_tag_id>921</primary_tag_id>
    	<secondary_tags>919</secondary_tags>
    	<name>Springfield Community College</name>
    	<address_1>630 Stim St. #200</address_1>
    	<address_2>Suite B</address_2>
    	<city>Springfield</city>
    	<state>VA</state>
    	<postal_code>95814</postal_code>
    	<phone_number>5559200157</phone_number>
    	<display_url>SpringfieldCollege.com</display_url>
    	<website_url>http://ua1.ybsa.int:8080/trackingenginewebapp/tracking.html?MB_ID=43209</website_url>
    	<tagline>Bachelor and Master's degree programs designed just for you! Visit us today.</tagline>
    	<menu_link></menu_link>
    	<reservation_link>
    	</reservation_link>
    	<owners_message>Serving the Region for over 30 years, the University Campus is located in downtown near the Capitol.</owners_message>
    	<bullet_1>Bachelor and Master's Degrees</bullet_1>
    	<bullet_2>Serving the Region for 30 Years.</bullet_2>
    	<bullet_3>Evening/Day Classes.</bullet_3>
    	<facebook_username></facebook_username>
    	<twitter_handle></twitter_handle>
    	<image_path></image_path>
    	<customer_message_url></customer_message_url>
    	<business_hours>Sun,Sat Closed Mon-Thu 9am-5pm Fri 9am-4:40pm</business_hours>
		<suppress_phone>1</suppress_phone>
		<suppress_address>1</suppress_address>
    	<is_tracking_enabled>1</is_tracking_enabled>
    	<parking></parking>
		<expertise></expertise>
    	<insurance></insurance>
    	<license></license>
    	<service_provider></service_provider>
    	<mobile_number></mobile_number>
    	<tip_text></tip_text>
    	<tip_title></tip_title>
    	<response>
    		<code>SUCCESS</code>
    		<field></field>
    		<message>Success</message>
    	</response>
    </place>
    <place>
    	<place_id>605310023</place_id>
    	<external_place_id>5320920_a</external_place_id>
    	<primary_tag_id>921</primary_tag_id>
    	<secondary_tags>4193</secondary_tags>
    	<name>Sylar Community College</name>
    	<address_1>5693  Rooster Rd</address_1>
    	<address_2></address_2>
    	<city>Orlando</city>
    	<state>FL</state>
    	<postal_code>32819</postal_code>
    	<phone_number>5558779639</phone_number>
    	<display_url>Our Schools</display_url>
    	<website_url>http://uatkopwrct01.ss.edu:8080/trackingenginewebapp/</website_url>
    	<tagline>Bachelor and Master's degree programs designed just for you! Visit us today.</tagline>
    	<menu_link></menu_link>
    	<reservation_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.</owners_message>
    	<bullet_1>BS and MS Degrees</bullet_1>
    	<bullet_2>Serving the Region for 30 Years.</bullet_2>
    	<bullet_3>Online Classes Available.</bullet_3>
    	<facebook_username></facebook_username>
    	<twitter_handle></twitter_handle>
    	<image_path></image_path>
    	<customer_message_url></customer_message_url>
    	<business_hours>Open 24 Hours</business_hours>
    	<suppress_phone>1</suppress_phone>
    	<suppress_address>1</suppress_address>
    	<is_tracking_enabled>1</is_tracking_enabled>
    	<parking>Parking in back.  Street parking in front.</parking>
		<expertise></expertise>
		<insurance></insurance>
    	<license></license>
    	<service_provider></service_provider>
    	<mobile_number></mobile_number>
		<tip_text></tip_text>
 		<tip_title></tip_title>
    	<response>
    		<code>SUCCESS</code>
    		<field></field>
    		<message>Success</message>
    	</response>
    </place>
</places>
<response>
    <code>SUCCESS</code>
    <field></field>
    <message>Success</message>
</response>
</results>

Error Reporting

Parameter	Error Message

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)

{
  "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)

{
  "totalNumEntries": 0,
  "places": [],
  "response": {
    "code": "PARAMETER_REQUIRED",
    "message": "The parameter, place_ids or external_place_ids, is required but has not been supplied.",
    "field": "place_ids or external_place_ids"
  }
}

XML Error Reponse

 <results>
    <totalNumEntries>0</totalNumEntries>
    <places/>
    <response>
        <code>PARAMETER_REQUIRED</code>
        <field>place_ids or external_place_ids</field>
        <message>The parameter, place_ids or external_place_ids, is required but has not been supplied.</message>
    </response>
</results>

Places Mutate Endpoint

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

api.citygrid.com/content/places/v2/mutate

Input data such as request parameters are subject to Places Management APIf ield 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.

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

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

Field	Description	Required

Places Management API

Introduction

Contents

Places Get Endpoint

Request Parameters

Get Header values

Request Example

Response Parameters

Places Page

Place

Media Types Supported

Response Examples

JSON Response

XML Response

Error Reporting

JSON Error Response (single place error, full request SUCCESS)

JSON Error Response (full request error)

XML Error Reponse

Request Parameters