Documentation

# Place Fields

Once you have a place_id from a Places, you can request more details about a particular establishment or point of interest by initiating a Place Fields request. A Place Fields request returns more comprehensive information about the indicated place such as its complete address, phone number.

# Place Fields Requests

A Place Fields request is an HTTP URL of the following form:

https://apis.geodir.co/places/fields/v1/**output**?**parameters**

where output may be either of the following values:

  • json (recommended) indicates output in JavaScript Object Notation (JSON); or
  • xml indicates output in XML

Some parameters are required while some are optional. As is standard in URLs, parameters are separated using the ampersand (&) character.

Required parameters in a places request:

  • place_id: A textual identifier that uniquely identifies a place, returned from a Place. For more information about placeli IDs, see the Place ID overview
  • key: Your application's API key. This key identifies your application for purposes of quota management. Learn how to obtain your API key.

# Fields

# Find Place Fields examples

The following example requests the details of a place by places_id, and includes the name and phone fields:

This request demonstrates using the JSON output flag:

https://apis.geodir.co/places/fields/v1/json?place_id=6bf0e3e686f1db678ba68c38ce7d98427e&key=YOUR_KEY

See below the sample JSON responses.

{
    "status": "OK",
    "category": [
        "route_number",
        " geocode"
    ],
    "address_segments": [
        {
            "name": "1597",
            "name_abbr": "1597",
            "types": [
                "route_number"
            ]
        },
        {
            "name": "San Carlos",
            "name_abbr": "San Carlos",
            "types": [
                "route"
            ]
        },
        {
            "name": "Jirón",
            "name_abbr": "Jr",
            "types": [
                "route_type"
            ]
        },
        {
            "name": "Lima",
            "name_abbr": "Lima",
            "types": [
                "admin_level_1",
                "political"
            ]
        },
        {
            "name": "15",
            "name_abbr": "15",
            "types": [
                "admin_level_1_code",
                "political"
            ]
        },
        {
            "name": "Lima",
            "name_abbr": "Lima",
            "types": [
                "admin_level_2",
                "political"
            ]
        },
        {
            "name": "1501",
            "name_abbr": "1501",
            "types": [
                "admin_level_2_code",
                "political"
            ]
        },
        {
            "name": "El Agustino",
            "name_abbr": "El Agustino",
            "types": [
                "admin_level_3",
                "political"
            ]
        },
        {
            "name": "150111",
            "name_abbr": "150111",
            "types": [
                "admin_level_3_code",
                "political"
            ]
        },
        {
            "name": "El Agustino Zona 4",
            "name_abbr": "El Agustino Zona 4",
            "types": [
                "sublocality",
                "political"
            ]
        },
        {
            "name": "Pueblo Joven",
            "name_abbr": "Pjj",
            "types": [
                "sublocality_type"
            ]
        },
        {
            "name": "Perú",
            "name_abbr": "PE",
            "types": [
                "country",
                "political"
            ]
        },
        {
            "name": "15006",
            "name_abbr": "15006",
            "types": [
                "postal_code"
            ]
        }
    ],
    "standard_address": "Jirón San Carlos 1597, El Agustino, Lima, Perú",
    "geometry": {
        "coordinates": {
            "lat": -12.0447283,
            "lon": -76.9998987
        }
    },
    "place_id": "NTk1MmE1NjEtZDViNS01NGIwLWE5OGUtYmEzZGE5NjM0OTcz",
    "hours": "",
    "phone": ""
}

# Status Codes

The "status" field within the place response object contains the status of the request, and may contain debugging information to help you track down why the place requesta faildes. The "status" field may contain the following values:

  • "OK" indicates that no errors occurred; the place was successfully parsed and at least one geocode was returned.
  • "ZERO_RESULTS" indicates that the referenced location (place_id) was valid but no longer refers to a valid result. This may occur if the establishment is no longer in business.
  • "OVER_QUERY_LIMIT" indicates any of the following:
    • You have exceeded the limits
    • Billing has not been enabled on your account.
    • The provided method of payment is no longer valid (for example, a credit card has expired).
  • "REQUEST_DENIED" indicates that your request was denied, generally because the key parameter is invalid.
  • "INVALID_REQUEST" generally indicates that the query (place_id) is missing.
  • "UNKNOWN_ERROR" indicates a server-side error; trying again may be successful.
  • "NOT_FOUND" indicates that the reference location (place_id) was not found in the Places database.

# Place Fields Results

When the Places service returns results from a fields request, it places them within a single result. Because place data results cannot be empty, only place results with data are returned. Each result may contain the following fields:

  • address_segments[] is an array containing the separate segments applicable to this address. Each address segments typically contains the following fields:
    • types[] is an array indicating the  of the address segments. See the list of supported types.
    • name is the full text description or name of the address segments as returned by the Places.
    • name_abbr is an abbreviated textual name for the address segments, if available. For example, an address segment for the country of Peru may have a name of "Peru" and a name_abbr of "PE" using the 2-letter abbreviation.

Note the following facts about the address_segments[] array:

  • The array of address segments may contain more segments than the standard_address
  • The array does not necessarily include all the political entities that contain an address, apart from those included in the standard_address. To retrieve all the political entities that contain a specific address, you should use reverse geocoding, passing the latitude/longitude of the address as a parameter to the request.
  • The format of the response is not guaranteed to remain the same between requests. In particular, the number of address_segments varies based on the address requested and can change over time for the same address. A component can change position in the array. The type of the segment can change. A particular segment may be missing in a later response.
  • standard_address is a string containing the human-readable address of this place. Often this address is equivalent to the "postal address"
  • geometry contains geometry information about the result, generally including the location (geocode) of the place and (optionally) the bbox identifying its general area of coverage.
  • phone contains the place's phone number in international format. International format includes the country code, and is prefixed with the plus (+) sign. For example, the int_phone for Geodir office is +51 1 305 5049.
  • hours: contains the information of opening periods
  • place_id: A textual identifier that uniquely identifies a place. To retrieve information about the place, pass this identifier in the placeId field of a Places API request. For more information about place IDs, see the place ID overview.
  • type[] contains an array of feature types describing the given result. See the list of supported types. XML responses include multiple type elements if more than one type is assigned to the result.
Last updated: 09/18/2023, 10:30:49 PM

← Autocomplete →