GET frame

Used to retrieve/view a frame.

When accessed via a GET request this API method will return a list of all frames. By specifying a id parameter you can retrieve details about a specific frame. The result will contain a paging object with details on the total pages and records within the resultset. You'll need to move through the pages via the page parameter in the URL.

INPUT

As this method is accessed via a GET request there is no HTTP body so options can be specified via the URL.

parameter type description
id int (optional) a frame identifier to restrict results to
previous_frame_id int (optional) a previous frame identifier to restrict results to
media_owner int (optional) restrict results to frames from this media owner.
sales_code string (optional) restrict results to frames with this sales code
space_format_id int (optional) restrict results to frames with this SPACE format identifier
frame_type int (optional) restrict results to frames with this frame type
faces int (optional) restrict results to frames with this number of faces
illumination int (optional) restrict results to frames with this illumination type
environment_type string (optional) restrict results to frames with this environment type
closed int (optional) restrict results to open, closed or open & closed frames by setting the value to 0, 1 or 2 respectively
on_route int (optional) restrict results to not on-route, on-route or both on & not on-route frames by setting the value to 0, 1 or 2 respectively
address string (optional) complete address to search on. Partial matches are not supported.
location string (optional) complete location to search on. Partial matches are not supported.
changed_date string (optional) restricts results to only frames that have been changed since this date. Registered changes do not include changes to IMSWorldGeodeticCoordinates or IMSMapID, the date of any changes to these fields are recorded separately. Date must be formatted as 2015-04-01T08:00:00
ims_changed_date string (optional) restricts results to only frames that have had the IMSWorldGeodeticCoordinates or IMSMapID data changed since this date. Date must be formatted as 2015-04-01T08:00:00
town_id int (optional) restricts results to only frames that are within a specific town. See GET town for available options.
tv_region_id int (optional) restricts results to only frames that are within a TV region. See GET tv-region for available options.
conurbation_id int (optional) restricts results to only frames that are within a specific conurbation. See GET conurbation for available options.
locality_id int (optional) restricts results to only frames that are associated with a specific locality. See GET locality for available options.
environment_group_id int (optional) restricts results to only frames with this environment group. See GET environment-group for available options.
format_group_id int (optional) restricts results to only frames with this format group. See GET format-group for available options.
(*) proximity_distance int (optional) restricts results to only frames that are greater than or equal to this distance (in metres) from any proximity_location's. If proximity_distance is specified without an accompanying proximity_location then this distance will apply to all sensitive locations.
(*) proximity_location string (optional) goes hand in hand with proximity_distance to restrict the proximity_distance to the supplied sensitive locations. This is a comma separated list which can include values of school, playground and place_of_worship. If an empty string is submitted for this value then it'll be assumed that it applies to all sensitive locations (i.e same as setting to school,playground,place_of_worship)
page int (optional) move through a resultset to the requested page
page_size int (optional) the maximum number of frame records per page

For media_owner, dimension_code, frame_type, illumination and environment_type you can see their respective API methods for allowable values.

(*) Available for Proximity data subscribers. For further information contact space@mediatel.co.uk.

OUTPUT - JSON sample

If accessing GET /api/frame?space_format_id=1 the following JSON would be returned:

{
    "data": [{
        "FrameID": 2000000051,
        "LocationDescription": "Some place2",
        "SalesCode": "19C",
        "Format": {
            "Code": "12",
            "SpaceFormatID": 1,
            "Width": 0.56,
            "Height": 0.24,
            "SurfaceArea": 0.13
        },
        "FrameType": 1,
        "Faces": 1,
        "Illumination": 1,
        "Environment": {
            "Type": "Roadside",
            "Description": "Roadside",
            "Attributes": [{
                    "Type": "WorldGeodeticCoordinate",
                    "Value": "49.76680500,-7.49999999"
                },
                {
                    "Type": "PostCode",
                    "Value": "SM12EA"
                },
                {
                    "Type": "Address",
                    "Value": "address value"
                }
            ]
        },
        "Distance": {
            "PrimarySchool": 404,
            "PrimarySchoolName": "Hallfield Primary School",
            "SecondarySchool": 848,
            "SecondarySchoolName": "Ashbourne Independent Sixth Form College",
            "SpecialNeedsSchool": 559,
            "SpecialNeedsSchoolName": "College Park School",
            "FurtherSchool": 6238,
            "FurtherSchoolName": "Putney High School",
            "PlaceOfWorship": "943",
            "Playground": "608",
            "UpdateDateTime": "2016-02-29 23:41:46"
        },
        "UpdateDateTime": "2015-02-25 14:00:34",
        "ClosedDate": null,
        "MediaOwner": "MediaTel",
        "MediaOwnerID": 1,
        "MediaOwnerFrameReference": "BSY03B",
        "LegacySiteNumber": "SITE123456",
        "Tags": [
            1,
            8
        ],
        "Localities": [
            1
        ],
        "TownName": "Sutton",
        "TvRegionName": "London",
        "ConurbationName": "Greater London",
        "EnvironmentGroup": "Roadside",
        "EnvironmentGroupID": 4,
        "FormatGroup": "Bus Sizes",
        "FormatGroupID": 10,
        "LinkedAssetID": 3000000004,
        "LinkedAssetDescription": "Description of Linked Asset ID 3000000004"
    }],
    "paging": {
        "page": 723,
        "page_size": 100,
        "total_pages": 723,
        "total_records": 72204
    }
}
        

A "data" element that contains an array of frames defined as follows:

FrameID - int - the unique identifier used within SPACE to reference the frame

LocationDescription - string - a description of the location of the frame

SalesCode - string - the sales code as set for the frame

Format - array - an array of format data defined as follows:

  • SpaceFormatID - int - the unique identifier for this format

  • Width - float - width in meters

  • Height - float - height in meters

  • SurfaceArea - float - surface area in square meters

FrameType - int - the type of frame (see relevant GET API method)

Faces - int - the number of faces for the frame

Illumination - int - the type of illumination (see relevant GET API method)

Environment - array - an array of environment data

    Type - string - the environment type

    Attributes - array - an array of attributes specifically for this environment

      Type - string - attribute type

      Value - string- attribute value

(*) Distance - array - an array of distance data calculated as the crow flies

  • PrimarySchool - int - distance in metres to the nearest primary school

  • PrimarySchoolName - string - name of the nearest primary school

  • SecondarySchool - int - distance in metres to the nearest secondary school

  • SecondarySchoolName - string - name of the nearest secondary school

  • SpecialNeedsSchool - int - distance in metres to the nearest special needs school

  • SpecialNeedsSchoolName - string - name of the nearest special needs school

  • FurtherSchool - int - distance in metres to the nearest further education school

  • FurtherSchoolName - string - name of the nearest further education school

  • PlaceOfWorship - int - distance in metres to the nearest place of worship

  • Playground - int - distance in metres to the nearest playground

  • UpdateDateTime - float - date/time that distances were last updated (YYYY-MM-DD HH:ii:ss)

UpdateDateTime - string - date/time that the frame was last updated (YYYY-MM-DD HH:ii:ss)

ClosedDate - string - date that the frame was closed, can be null

MediaOwner - string - media owner company name

MediaOwnerID - int - media owner company identifier

MediaOwnerFrameReference - string - media owner frame reference

LegacySiteNumber - string - legacy site number

PreviousFrameID - int - previous frame identifier that was associated with this frame

Tags - array - an array of tags associated with the frame

Localities - array - an array of localities associated with the frame

TownName - string - town

TvRegionName - string - TV region name

ConurbationName - string - Conurbation name

EnvironmentGroup - string - Environment group

EnvironmentGroupID - int - Environment group identifier

FormatGroup - string - Format group

FormatGroupID - int - Format group identifier

LinkedAssetID - int - Linked Asset identifier

LinkedAssetDescription - string - Linked Asset description

paging - array - an array of paging date for the resultset data defined as follows:

  • page - int - the current page for this request

  • page_size - int - the maximum number of frame records per page

  • total_pages - int - the total number of pages this request generated

  • total_records - int - the total number of frame records this request generated

MediaOwnerFrameReference will only be returned in requests for frames where the user is the media owner.

PreviousFrameID will only be returned in requests for frames where a previous frame identifier has been assigned.

(*) Available for Proximity data subscribers. For further information contact space@mediatel.co.uk.