Points of Interest Details

The Points of Interest (POI) Details endpoint provides additional information about the POIs including: rating, price range, 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>

curl command format

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

HTTP Request headers

The following table describes HTTP Request headers.

▲ Return to top

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.

Response body

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

{
    "id": "Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=",
    "result": {
        "rating": {
            "totalRatings": 136,
            "value": 8.97,
            "minValue": 0,
            "maxValue": 10
        },
        "priceRange": {
            "label": "Moderate",
            "value": 2,
            "minValue": 1,
            "maxValue": 4
        },
        "photos": [
            {
                "id": "f45c987a-1cd9-11ea-978f-2e728ce88125"
            },
            {
                "id": "f45c9b68-1cd9-11ea-978f-2e728ce88125"
            },
            {
                "id": "f45c9d20-1cd9-11ea-978f-2e728ce88125"
            },
            {
                "id": "f45c9e6a-1cd9-11ea-978f-2e728ce88125"
            },
            {
                "id": "f45ca0ae-1cd9-11ea-978f-2e728ce88125"
            }
        ],
        "reviews": [
            {
                "text": "De Melkweg – or Milky Way – has a long reputation as a live venue and will never let you down. A must-see on your night out in Amsterdam!",
                "date": "2019-02-16"
            },
            {
                "text": "Don't talk during gigs, it's bloody annoying!",
                "date": "2018-07-29"
            },
            {
                "text": "Friday May 31st at Melkweg: Lovebirds Amsterdam, featuring DJ's D-Rok (NL) & Simbad (UK) with a warm mix of soul, funk, hiphop, jazz, boogie, disco and house.",
                "date": "2019-03-05"
            },
            {
                "text": "Su bedava olsun",
                "date": "2019-11-01"
            },
            {
                "text": "Offers a program that unites five artistic disciplines under one roof: dance/theatre, film, photography, and media art.",
                "date": "2017-01-23"
            }
        ]
    }
}

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

<response>
    <id>Rm91cnNxdWFyZTo0YTI3MDNjOGY5NjRhNTIwNjY4NTFmZTM=</id>
    <result>
        <rating>
            <totalRatings>148</totalRatings>
            <value>8.97</value>
            <minValue>0</minValue>
            <maxValue>10</maxValue>
        </rating>
        <priceRange>
            <label>Moderate</label>
            <value>2</value>
            <minValue>1</minValue>
            <maxValue>4</maxValue>
        </priceRange>
        <photos>
            <photo>
                <id>f45c987a-1cd9-11ea-978f-2e728ce88125</id>
            </photo>
            <photo>
                <id>f45c9b68-1cd9-11ea-978f-2e728ce88125</id>
            </photo>
            <photo>
                <id>f45c9d20-1cd9-11ea-978f-2e728ce88125</id>
            </photo>
            <photo>
                <id>f45c9e6a-1cd9-11ea-978f-2e728ce88125</id>
            </photo>
            <photo>
                <id>f45ca0ae-1cd9-11ea-978f-2e728ce88125</id>
            </photo>
        </photos>
        <reviews>
            <review>
                <text>De Melkweg – or Milky Way – has a long reputation as a live venue and will never let you down. A must-see on your night out in Amsterdam!</text>
                <date>2019-02-16</date>
            </review>
            <review>
                <text>Don't talk during gigs, it's bloody annoying!</text>
                <date>2018-07-29</date>
            </review>
            <review>
                <text>Friday May 31st at Melkweg: Lovebirds Amsterdam, featuring DJ's D-Rok (NL) & Simbad (UK) with a warm mix of soul, funk, hiphop, jazz, boogie, disco and house.</text>
                <date>2019-03-05</date>
            </review>
            <review>
                <text>Su bedava olsun</text>
                <date>2019-11-01</date>
            </review>
            <review>
                <text>Offers a program that unites five artisctic disciplines under one roof: dance/theatre, film, photography, and media art.</text>
                <date>2017-01-23</date>
            </review>
        </reviews>
    </result>
</response>

Usage of Points of Interest Details

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

• You shall attribute all Results delivered by the Extended Search-Points of Interest Details API and Points of Interest Photos API as being ‘powered by Foursquare’.
• You shall not use any Results delivered by the Extended Search-Points of Interest Details API and Points of Interest Photos API to create, improve, or edit a venue or point of interest database.
• You shall not cache any Results delivered by the Extended Search-Points of Interest Details API and Points of Interest Photos API 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