Points of Interest Details

The Points of Interest (POI) Details endpoint provides additional information about the POIs including: rating, price range, social media links (Facebook, Instagram, Twitter), photo IDs, and user reviews.

HTTPS methods: GETHEAD

URL format

For ease of viewing and identification:

• Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
• See the following request parameters section with the Required and Optional parameters tables for these values.

https://<baseURL>/search/<versionNumber>/poiDetails.<ext>?key=<Your_API_Key>&id=<id>[&sourceName=<sourceName>]

curl command format

curl 'https://<baseURL>/search/<versionNumber>/poiDetails.<ext>?key=<Your_API_Key>&id=<id>[&sourceName=<sourceName>]'

Request parameters

The following table describes the parameters that can be used in a request.

• Required parameters must be used or the call will fail.
• Parameters and values are case-sensitive.

▲ Return to top

HTTP request headers

The following table describes HTTP request headers.

▲ Return to top

Response body

If the <ext> parameter value is set to .json, the response will be a JSON object with the following structure:

{
    "id": "Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=",
    "result": {
        "description": "Award winning restaurant founded by the De Visscher family.",
        "rating": {
            "totalRatings": 214,
            "value": 8.84,
            "minValue": 0,
            "maxValue": 10
        },
        "priceRange": {
            "label": "Moderate",
            "value": 2,
            "minValue": 1,
            "maxValue": 4
        },
        "socialMedia": [
            {
                "name": "facebook",
                "url": "https://facebook.com/profile.php?id=564078493731401"
            }
        ],
        "photos": [
            {
                "id": "23bc3b0b-d33d-3c07-8612-e660ea7c0864"
            },
            {
                "id": "df424a18-8710-3f85-952f-5528ed9b3e46"
            },
            {
                "id": "9a27ffba-c7b6-3d15-9334-417a3281a6c0"
            },
            {
                "id": "6b49c97b-da5c-3dc3-b802-aa83e14337e7"
            },
            {
                "id": "1dd59289-87f2-30e0-bd32-e4f08775889f"
            }
        ],
        "reviews": [
            {
                "text": "Finger foods bölümündeki kalamar ve ahtapot çok lezzetli, günün balığı olarak da ızgara çupra seçtik o da lezzetli, bu menü 2 kişi için ideal. Beyaz şarap olarak chardonnay seçtik italyan, o da iyiydi",
                "date": "2020-02-23"
            },
            {
                "text": "fresh oysters, square lobster soup",
                "date": "2020-01-08"
            },
            {
                "text": "My favorite in Amsterdam!",
                "date": "2020-01-01"
            },
            {
                "text": "Oysters are delicious, catch of the day dish was very good! Soup is tasty, but could be better. Be careful with the price.",
                "date": "2016-05-31"
            },
            {
                "text": "Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.",
                "date": "2015-03-29"
            }
        ],
        "popularHours": [
          {
            "dayOfWeek": 1,
            "timeRanges": [
              {
                "startTime": {
                  "hour": 12,
                  "minute": 0
                },
                "endTime": {
                  "hour": 16,
                  "minute": 0
                }
              }
            ]
          },
          {
            "dayOfWeek": 2,
            "timeRanges": [
              {
                "startTime": {
                  "hour": 12,
                  "minute": 0
                },
                "endTime": {
                  "hour": 14,
                  "minute": 0
                }
              }
            ]
          },
          {
            "dayOfWeek": 3,
            "timeRanges": [
              {
                "startTime": {
                  "hour": "12",
                  "minute": 0
                },
                "endTime": {
                  "hour": "14",
                  "minute": 0
                }
              }
            ]
          },
          {
            "dayOfWeek": 4,
            "timeRange": [
              {
                "startTime": {
                  "hour": 12,
                  "minute": 0
                },
                "endTime": {
                  "hour": 14,
                  "minute": 0
                }
              }
            ]
          },
          {
            "dayOfWeek": 5,
            "timeRange": [
              {
                "startTime": {
                  "hour": 12,
                  "minute": 0
                },
                "endTime": {
                  "hour": 14,
                  "minute": 0
                }
              },
              {
                "startTime": {
                  "hour": 17,
                  "minute": 0
                },
                "endTime": {
                  "hour": 19,
                  "minute": 0
                }
              },
              {
                "startTime": {
                  "hour": 21,
                  "minute": 0
                },
                "endTime": {
                  "hour": 2,
                  "minute": 0
                }
              }
            ]
          },
          {
            "dayOfWeek": 6,
            "timeRanges": [
              {
                "startTime": {
                  "hour": 18,
                  "minute": 0
                },
                "endTime": {
                  "hour": 3,
                  "minute": 0
                }
              }
            ]
          }
        ]
    }
}

If the <ext> parameter value is set to .xml, the response will be a XML format with the following structure:

<response>
    <id>Rm91cnNxdWFyZTo1NTExYWY3MTQ5OGUwZjc4OWNkODRhZjI=</id>
    <result>
        <description>Award winning restaurant founded by the De Visscher family.</description>
        <rating>
            <totalRatings>214</totalRatings>
            <value>8.84</value>
            <minValue>0</minValue>
            <maxValue>10</maxValue>
        </rating>
        <priceRange>
            <label>Moderate</label>
            <value>2</value>
            <minValue>1</minValue>
            <maxValue>4</maxValue>
        </priceRange>
        <socialMedia>
            <media>
                <name>facebook</text>
                <url>https://facebook.com/profile.php?id=564078493731401</date>
            </media>
        </socialMedia>
        <photos>
            <photo>
                <id>23bc3b0b-d33d-3c07-8612-e660ea7c0864</id>
            </photo>
            <photo>
                <id>df424a18-8710-3f85-952f-5528ed9b3e46</id>
            </photo>
            <photo>
                <id>9a27ffba-c7b6-3d15-9334-417a3281a6c0</id>
            </photo>
            <photo>
                <id>6b49c97b-da5c-3dc3-b802-aa83e14337e7</id>
            </photo>
            <photo>
                <id>1dd59289-87f2-30e0-bd32-e4f08775889f</id>
            </photo>
        </photos>
        <reviews>
            <review>
                <text>Finger foods bölümündeki kalamar ve ahtapot çok lezzetli, günün balığı olarak da ızgara çupra seçtik o da lezzetli, bu menü 2 kişi için ideal. Beyaz şarap olarak chardonnay seçtik italyan, o da iyiydi</text>
                <date>2020-02-23</date>
            </review>
            <review>
                <text>fresh oysters, square lobster soup</text>
                <date>2020-01-08</date>
            </review>
            <review>
                <text>My favorite in Amsterdam!</text>
                <date>2020-01-01</date>
            </review>
            <review>
                <text>Oysters are delicious, catch of the day dish was very good! Soup is tasty, but could be better. Be careful with the price.</text>
                <date>2016-05-31</date>
            </review>
            <review>
                <text>Прекрасный ресторан с морепродуктами! Если соберетесь туда вечером - забронируйте заранее столик у них на сайте.</text>
                <date>2015-03-29</date>
            </review>
        </reviews>
        <popularHours>
            <hours>
                <dayOfWeek>1</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>12</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>16</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
            <hours>
                <dayOfWeek>2</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>12</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>14</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
            <hours>
                <dayOfWeek>3</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>12</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>14</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
            <hours>
                <dayOfWeek>4</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>12</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>14</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
            <hours>
                <dayOfWeek>5</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>12</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>14</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                    <timeRange>
                        <startTime>
                            <hour>17</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>19</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                    <timeRange>
                        <startTime>
                            <hour>21</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>2</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
            <hours>
                <dayOfWeek>6</dayOfWeek>
                <timeRanges>
                    <timeRange>
                        <startTime>
                            <hour>18</hour>
                            <minute>0</minute>
                        </startTime>
                        <endTime>
                            <hour>3</hour>
                            <minute>0</minute>
                        </endTime>
                    </timeRange>
                </timeRanges>
            </hours>
        </popularHours>
    </result>
</response>

Usage of Points of Interest Details

With respect to the Points of Interest Details endpoint, the following applies:

• You shall attribute all results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint as being ‘powered by Foursquare’.
• You shall not use any results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint to create, improve, or edit a venue or point of interest database.
• You shall not cache any results delivered by the Extended Search API Points of Interest Details endpoint and Points of Interest Photos endpoint for more than 30 days.
• See the Terms and Conditions for more details.

Response fields

The following table describes all of the fields that can appear in a response. Fields are listed by the response section they belong to and in the order that they appear in the response.

HTTP response codes

{
    "id": "Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=",
    "result": {}
}

<response>
    <id>Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=</id>
    <result></result>
</response>

▲ Return to top

Response headers

▲ Return to top

Error response

The error response content type depends on the ext parameter.

Error response example (JSON)

{
  "message":"Missing parameter 'parameterName'",
  "detailedError":{
    "code":"MissingParameter",
    "message":"Missing required parameter 'parameterName'.",
    },
  "httpStatusCode":"400"
}

Error response example (XML)

<ErrorEvResponse>
  <message>Missing parameter 'parameterName'</message>
  <detailedError>
    <code>MissingParameter</code>
    <message>Missing required parameter 'parameterName'.</message>
  </detailedError>
</ErrorEvResponse>

▲ Return to top

Error response fields