/
Places Status API

CityGrid Advertising APIs

Places Status API

Owned by Former user (Deleted)
Last updated: Mar 20, 2013Version comment

Introduction

The CityGrid Places Status API is part of the Advertising API suite and is intended to help a partner or their advertisers understand if a local business, or Place, has been successfully added to or updated within the CityGrid Places dataset.  A new partner is only enabled to create listings after an internal review of their data quality.  Partners who cannot create listings must provide data that matches to an existing listing, or that place will not go live and will not generate connections.  There are multiple reasons a listing may not have matched and gone live; this is the information this API provides with the intent of providing transparency and a way for a partner and merchants to resolve these issues on their own.  Report information is available in both JSON or XML.

Contents

Endpoint

The operation is invoked via HTTPS GET to:

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

Request Parameters

Parameter

Description

Required

Type

Default

Example

place_id

Comma-separated list of place IDs. If specified, external_places_id must be left empty.

No

Long

 

4352,8473,242

external_place_id

Comma-separated list of external IDs of the place. If specified, place_ids must be left empty.

No

String

 

1,2,3,4

Request Header Values

Header

Description

Required

Valid Values

Accept

Requested format for the response

Yes

application/json
application/xml

authToken

Authentication Token from the Places Status API

Yes

Valid token

developerToken

The token received during registration

Yes

Valid token

Request Examples

Example 1: Get the status for place by place_ids that is owned by the authToken.
curl -X GET \
     -H 'Accept:application/json' \
     -H 'authToken:mytoken' \
    'http://api.citygrid.com/content/places/v2/status?place_id=605659852'
Example 2: Get the status of multiple places using external place IDs
curl -X GET \
     -H 'Accept:application/json' \
     -H 'authToken:mytoken' \
    'http://api.citygrid.com/content/places/v2/status?external_place_id=23424,452,455'

Response Properties

Property

Type

Description

response

Response Metadata

(See complete response descriptions)

totalNumEntries

Integer

Total number of places in the response.

place_id

String

The place ID.

external_place_id

String

External place ID of the campaign.

status

{PENDING_BUSINESS_MATCH,

MATCHED,ENTITY_NOT_FOUND}

Status of the places in the system:

PENDING_BUSINESS_MATCH: Place is pending on matching process. If a place is in this state for more than a couple days then no match exists. Please verify accuracy of name, address and phone provided.

MATCHED: Place is matched and active.

ENTITY_NOT_FOUND: There are no places found given the id/external place id

create_date

String

When places is submitted. Returns empty if place not found

Response Examples

Success Response

The following shows success responses in JSON and XML format.

JSON
{
   "totalNumEntries":3,
   "placeStatus":[
      {
      "place_id":"11489139",
      "external_place_id","1234",
      "status":"PENDING_BUSINESS_MATCH",
      "create_date":"20120920"
      },
      {
      "place_id":"68687",
      "external_place_id","1235",
      "status":"MATCHED",
      "create_date":"20120920"
      },
      {
      "place_id":"11489139",
      "external_place_id","",
      "status":"ENTITY_NOT_FOUND",
      "create_date":""
      }
   ]
}
 
XML
<results>
   <totalNumEntries>1</totalNumEntries>
   <places>
      <place>
         <place_id>605659852</place_id>
         <external_place_id>605659852</external_place_id>
         <name>Valley VW</name>
         <status>MATCHED</status>
         <create_time>2012-04-19T08:51:36-07</create_time>
      </place>
   </places>
   <response>
      <code>SUCCESS</code>
      <field></field>
      <message>Success</message>
   </response>
</results>

Error Response

The following shows error responses (in JSON and XML format) when campaignId are not comma separated numbers.

JSON
{
  "totalNumEntries" : 0,
  "places" : [],
  "response" : {
      "code" : "PARAMETER_REQUIRED",
      "message" : "The parameter, place_id or external_place_id, is required but has not been supplied.",
      "field" : "place_id or external_place_id"
  }
}
XML
<results>
   <totalNumEntries>0</totalNumEntries><places/>
   <response>
      <code>PARAMETER_REQUIRED</code>
      <field>place_id or external_place_id</field>
      <message>The parameter, place_id or external_place_id, is required but has not been supplied.</message>  
   </response>
</results>