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 an 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.

Some parameters accept more than one value, these currently include: space_format_id, frame_type, environment_type, and conurbation_id. These values should be presented as a comma separated list (i.e. /api/frame?frame_type=1,2,3).

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
spot_length int (optional) restrict results to frames with a spot length value greater than or equal to the parameter value
break_length int (optional) restrict results to frames with a break length value greater than or equal to the parameter value
share_time int (optional) restrict results to frames with a share of time value greater than or equal to the parameter value
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 frames not to be submitted to Route, to be submitted to Route, or both 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
future_start_date int (optional) restrict results to exclude future frames or only include future frames by setting the value to 0 or 1 respectively
(*) proximity_distance int (optional) restricts results to only frames that are greater than or equal to this distance (in metres) from any proximity_location, 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": 3.05,
            "Height": 1.52,
            "SurfaceArea": 4.64
        },
        "FrameType": 3,
        "Faces": 2,
        "Illumination": 1,
        "Environment": {
            "Type": "Roadside",
            "Description": "Roadside",
            "Attributes": [
                 {
                     "Type": "IMSWorldGeodeticCoordinate",
                     "Value": "51.37705546,-0.27882552"
                },
                {
                    "Type": "Address",
                    "Value": "address value"
                },
                {
                    "Type": "PostCode",
                    "Value": "SM12EA"
                },
                {
                    "Type": "WorldGeodeticCoordinate",
                    "Value": "51.37705546,-0.27882552"
                },
                {
                    "Type": "SpotLength",
                    "Value": "10"
                },
                {
                    "Type": "BreakLength",
                    "Value": "6"
                },
                {
                    "Type": "ShareOfTime",
                    "Value": "62.5"
                }
            ]
        },
        "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",
            "UpdateDateTime": "2016-02-29 23:41:46"
        },
        "UpdateDateTime": "2015-02-25 14:00:34",
        "IMSUpdatedDateTime": "2017-05-10 09:05:34",
        "ClosedDate": null,
        "PreviousMediaOwner": null,
        "PreviousMediaOwnerID": null,
        "MediaOwner": "Mediatel",
        "MediaOwnerID": 1,
        "MediaOwnerStartDate": "2018-01-11",
        "MediaOwnerEndDate": null,
        "NewMediaOwner": null,
        "NewMediaOwnerID": null,
        "TransferDate": null,
        "LegacySiteNumber": "SITE123456",
        "OnRoute": 1,
        "Tags": [1,8],
        "Localities": [1],
        "Prohibitions": {
            "MediaOwnerCategories": [1, 2, 3]
         },
        "TownName": "Sutton",
        "TvRegionName": "London",
        "ConurbationName": "Greater London",
        "EnvironmentGroup": "Roadside",
        "EnvironmentGroupID": 4,
        "FormatGroup": "12 Sheets",
        "FormatGroupID": 3,
        "LinkedAssetID": 3000000004,
        "LinkedAssetReference": "Reference text",
        "LinkedAssetDescription": "Description of Linked Asset ID 3000000004",
        "RestrictedAssets": [],
        "MediaOwnerAttributes": null,
        "MediaOwnerFrameReference": "BSY03B",
        "PreviousFrameID": "2004605892"
    }],
    "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:

  • Code - string - the unique dimension identifier

  • 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

    Description - string - the environment description

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

      Type - string - attribute type

      Value - string- attribute value

MediaOwnerAttributes - object - media owner attribute data

    AttributeName:AttributeValue - key:value - paired media owner attributes and their associated values

(*) 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

  • 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)

IMSUpdatedDateTime - string - date/time that the IMS fields were last updated (YYYY-MM-DD HH:ii:ss)

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

PreviousMediaOwner - string - previous media owner company name

PreviousMediaOwnerID - int - previous media owner company identifier

MediaOwner - string - media owner company name

MediaOwnerID - int - media owner company identifier

MediaOwnerStartDate - string - date from which the media owner owned the frame

MediaOwnerEndDate - string - date from which the media owner no longer owned the frame

NewMediaOwner - string - media owner company name that frame is transferring to

NewMediaOwnerID - int - media owner company identifier that frame is transferring to

TransferDate - string - date from which new media owner will own frame

LegacySiteNumber - string - legacy site number

OnRoute - int - whether the frame is to be submitted to Route or not, specified by 1 or 0 respectively

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

Prohibitions - object - a collection of arrays representing different types of prohibitions associated with this frame, including MediaOwnerCategories

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

MediaOwnerFrameReference - string - media owner frame reference

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.