1. Home
  2. Programming
  3. Working with the Registry
  4. Reading the Registry
  5. EIDR API Proxy – HTTP and REST API Elements
  1. Home
  2. Programming
  3. EIDR API Proxy
  4. EIDR API Proxy – HTTP and REST API Elements
  1. Home
  2. Programming
  3. EIDR Input/Output Formats
  4. TSV (Input/Output)
  5. EIDR API Proxy – HTTP and REST API Elements
  1. Home
  2. Programming
  3. EIDR Input/Output Formats
  4. JSON (Output)
  5. EIDR API Proxy – HTTP and REST API Elements
  1. Home
  2. Programming
  3. EIDR API Proxy – HTTP and REST API Elements

EIDR API Proxy – HTTP and REST API Elements

This section discusses the API of the various services offered by the EIDR API Proxy, accessible only through the HTTPS protocol.

NOTE: HTTP will not be redirected automatically to HTTPS. You must use the HTTPS protocol directly.

Common HTTP Headers

As is the case with all REST implementations using HTTP, requests and responses vary in the HTTP method used for requests, HTTP headers, and the actual data transmitted between the server and the clients. The following sub-sections summarize the headers used for all the EIDR API Proxy requests and responses.

HTTP Request Headers

The EIDR API Proxy uses the following HTTP request headers for all service requests.

Header NameRequiredDescription
AcceptOptionalThe MIME type of the accepted response. Defaults to “application/json”. The allowed values are:
application/json
text/tab-separated-values
application/vnd.eidr.*
text/xml[1]
Overridden by any type or format HTTP query parameters.
AuthorizationConditional. Required only for Query.The required authentication and authorization credentials. See the “Authentication and Authorization” section below.
Content-TypeRequired for the POST methodDifferent POST APIs use different Content-Type headers
• resolve/POST: application/json
• query: text/xml for XPath (pass-through) queries
• query: application/json for JSON queries
HTTP Request Headers

NOTE: EIDR ignores any other request headers if specified in a request.

Authentication and Authorization

The EIDR API Proxy uses the standard HTTP Authorization header to pass both the authentication and authorization credentials. The EIDR API Proxy uses a proprietary authentication scheme (“Eidr”) that extends standard HTTP Basic authentication to incorporate both an EIDR User and an EIDR Party into the credentials, as detailed in EIDR REST API Reference.

A pseudo-grammar of the HTTP Authorization request header is shown below:

Authorization = "Eidr" + " " + UserID + ":" + PartyID + ":" + PasswordShadow;

PasswordShadow = Base64(MD5(Password));

NOTE: The “Eidr” authentication scheme token is case-insensitive.

NOTE: As required in Base64 encoding, the resulting string must include padding out to a multiple of 4 characters by appending “=” characters. In the case of a 128-bit MD5 hash, the base64 encoding results in a 24-character string ending in “==”. Some APIs, such as Perl’s md5_base64() function, leave the addition of padding to the caller. Also note that the base64 encoding of the MD5 hash is of the binary string, not of the hexadecimal text string.

Escaped Characters

JSON requires that certain characters be escaped when you wish to represent the literal character without having it be interpreted as JSON code.

Character glyph (name)JSON Escape
  (backspace)\b
  (form feed)\f
  (newline)\n
  (carriage return)\r
  (tab)\t
” (double quote)\”
\ (backslash)\\
JSON Character Escaping

The EIDR API Proxy passes requests on to the standard EIDR API, which is XML-based, so certain characters commonly used in the XML elements need to be escaped when they appear in metadata or a query string that will be sent on to the standard EIDR API, as noted in the table below.

Character glyph (name)XML Escape
” (double quote)"
‘ (apostrophe, back quote)'
< (less than)&lt;
> (greater than)&gt;
& (ampersand)&amp;
XML Character Escaping

NOTE: The double quote (“) is reserved in both JSON and XML and requires a different escape character depending on context. If the character appears within a string that will be interpreted as JSON by the API Proxy, use the JSON escape. If it appears in a string that will be passed on to the EIDR registry, then use the XML escape. If in doubt, defer to XML.

ERROR Codes and Descriptions

HTTP CodeNotes
200Response from the EIDR registry. If there is an error, it will be in the response body. See EIDR REST API Reference.
302XML resolution request redirected to the DOI proxy.
400• Unsupported content type: Type
• XML Redirect not supported (an XML-format request for something other than a single ID resolution)
• Bad page number: Number (pageNumber is out of bounds)
• Bad page size: Size (pageSize is out of bounds)
• pageSize Size is too large for type Type (see “API Information Service” for the specific limits)
• Full query result size Size too large for type Type (see “API Information Service” for the specific limits)
• Invalid ID: ID (the specified ID is not in the correct format)
• Invalid ‘ids’ array is request body (a resolve multiple request where at least one of the IDs is not in the correct format)
403• Authorization error (either credentials are required but not provided or invalid credentials were provided)
500• Invalid connector option
• Invalid query
• Unrecognized response from registry
• Unsupported type
• Misc. registry error (see EIDR REST API Reference)
HTTP Codes

NOTE: Please see EIDR REST API Reference for a list of the standard EIDR API error codes.

HTTP Response Headers

The EIDR API Proxy responds with the following headers:

Header NameDescription
Content-TypeThe Internet Media (MIME) Type of the response sent by the proxy to its clients. One of:
application/json; charset=UTF-8
text/tab-separated-values; charset=UTF-8 
DateThe time of the response. For example:
Mon, 08 Dec 2014 23:00:38 GMT
EIDR-VersionThis will always be the current version. For example: 2.6.0
HTTP Response Headers

Public Services API Proxy

This section defines the actual HTTP headers, parameters, and data transmitted for each of the services that may be accessed with or without EIDR API credentials.

Single resolutions are supported using HTTP GET. All other services are supported using HTTP POST.

Single ID Resolution service

This service resolves IDs the EIDR content, video service, or party databases.                                                             

NameValue                       
URLhttps://proxy.eidr.org/resolve/<asset ID>[2]
MethodHTTP GET
EncodingNone
HTTP Headers
NameTypeNotes
Accept See section “HTTP Request Headers”. Also allows the MIME types described in EIDR Resolution Proxies.
Authorization Optional. See section “HTTP Request Headers”.
HTTP Parameters
NameTypeNotes
typeEnumeration:Full, DOIKernel, SelfDefined, Simple, Provenance, AlternateIDs, LinkedAlternateIDRefer to the EIDR Registry Technical Overview for complete details. Defaults to Full. This field is case-insensitive.
formatEnumeration: json, tsv, xmlThe output data format. This field is case-insensitive.
Single ID Resolution Service Request
HTTP Response Headers
NameTypeNotes
Content-type See section “HTTP Response Headers”.
Data
ResultsJSON or TSVRefer to mapping tables below. If the request was for XML, the response is a redirect to https://doi.org as described in EIDR Resolution Proxies.
Single ID Resolution Service Response

Resolution Service Examples

An example of a resolution request is as follows:

GET https://proxy.eidr.org/<asset ID>?type=Full
HTTP/1.1

Accept: text/xml

An example of the response to a resolution request is as follows:

HTTP/1.1 200 OK

Content-Type: text/xml; charset=UTF-8

<Response JSON/TSV goes here>

Below is an example of a single ID resolution request for Full metadata in JSON (default) format using GET via cURL:

curl -L -X GET -H "Accept: application/vnd.eidr.full" https://proxy.eidr.org/resolve/10.5240/7FC6-3F8B-B85F-A1DA-E1F9-H

or

curl -L -X GET "https://proxy.eidr.org/resolve/10.5240/7FC6-3F8B-B85F-A1DA-E1F9-H?type=full"

Here is a sample JSON response to a resolution request for the Full view of a root object:

 {
   "ID": "10.5240/ABEC-F940-CC66-5394-7B3B-3",
   "StructuralType": "Abstraction",
   "Mode": "AudioVisual",
   "ReferentType": "Short",
   "ResourceName": {
     "ResourceName": "Paperman",
     "_lang": "en",
     "_titleClass": "release"
   },
   "OriginalLanguage": [
     {
       "OriginalLanguage": "en",
       "_mode": "Audio",
       "_type": "primary"
     }
   ],
   "AssociatedOrg": [
     {
       "_idType": "EIDRPartyID",
       "_organizationID": "10.5237/E872-28B7",
       "_role": "producer",
       "DisplayName": "Walt Disney Animation Studios"
     }
   ],
   "ReleaseDate": "2012-11-02",
   "CountryOfOrigin": [
     "US"
   ],
   "Status": "valid",
   "ApproximateLength": "PT7M",
   "AlternateID": [
     {
       "AlternateID": "tt2388725",
       "_type": "IMDB"
     },
     {
       "AlternateID": "7774265109340788112",
       "_domain": "comcast.com",
       "_type": "Proprietary"
     },
     {
       "AlternateID": "206798",
       "_domain": "webedia-group.com",
       "_type": "Proprietary"
     }
   ],
   "Administrators": {
     "Registrant": "10.5237/4C72-BE2C"
   },
   "Credits": {
     "Director": [
       {
         "DisplayName": "John Kahrs"
       }
     ]
   }
 }  

Here is a sample JSON response to a resolution request for the Self-Defined view of an Episode object:

 {
  "ID": "10.5240/8196-C6F4-3A4E-22CF-4FF6-Z",
  "StructuralType": "Abstraction",
  "ReferentType": "TV",
  "ResourceName": {
    "ResourceName": "Hollywood, Part 3",
    "_lang": "en",
    "_titleClass": "release"
  },
  "ReleaseDate": "1977",
  "Status": "valid",
  "ApproximateLength": "PT30M",
  "AlternateID": [
    {
      "AlternateID": "See-TiVo",
      "_domain": "tivo.com",
      "_relation": "Other",
      "_type": "Proprietary"
    },
    {
      "AlternateID": "HPDY1093",
      "_domain": "crownmedia.com",
      "_type": "Proprietary"
    },
    {
      "AlternateID": "tt0596235",
      "_relation": "IsSameAs",
      "_type": "IMDB"
    }
  ],
  "Administrators": {
    "Registrant": "10.5237/superparty"
  },
  "ExtraObjectMetadata": {
    "EpisodeInfo": {
      "Parent": "10.5240/1855-86AB-68B4-4D2A-6334-Z",
      "SequenceInfo": {
        "DistributionNumber": "2",
        "HouseSequence": {
          "md:HouseSequence": "93",
          "_domain": "eidr.org"
        }
      }
    }
  }
}

Here is a sample JSON response to a resolution request for the LinkedAlternateID view:

 {
   "ID": "10.5240/ABEC-F940-CC66-5394-7B3B-3",
   "LinkedAlternateID": [
     {
       "AlternateID": [
         {
           "value": "138744",
           "_domain": "thecinemasource.com",
           "_type": "Proprietary"
         }
       ]
     },
     {
       "AlternateID": [
         {
           "value": "895667",
           "_type": "IVA"
         }
       ]
     },
     {
       "AlternateID": [
         {
           "value": "771311371",
           "_domain": "flixster.com",
           "_type": "Proprietary"
         }
       ],
       "URL": [
         {
           "value": "http://www.rottentomatoes.com/m/771311371",
           "_type": "text/html"
         }
       ]
     },
     {
       "AlternateID": [
         {
           "value": "206798",
           "_domain": "webedia-group.com",
           "_type": "Proprietary"
         }
       ],
       "URL": [
         {
           "value": "http://www.allocine.fr/film/fichefilm_gen_cfilm=206798.html",
           "_type": "text/html"
         },
         {
           "value": "http://www.adorocinema.com/filmes/filme-206798/",
           "_type": "text/html"
         },
         {
           "value": "http://www.beyazperde.com/filmler/film-206798/",
           "_type": "text/html"
         },
         {
           "value": "http://www.filmstarts.de/kritiken/206798.html",
           "_type": "text/html"
         },
         {
           "value": "http://www.sensacine.com/peliculas/pelicula-206798/",
           "_type": "text/html"
         },
         {
           "value": "https://www.sensacine.com.mx/peliculas/pelicula-206798/",
           "_type": "text/html"
         }
       ]
     }
   ]
 } 

Multiple ID Resolution service

This service resolves a list of one or more EIDR IDs from the EIDR content, video service, or party databases in any order or combination.[3]              

NameValue                       
URLhttps://proxy.eidr.org/resolve
MethodHTTP POST
EncodingNone
HTTP Headers
NameTypeNotes
Accept See section “HTTP Request Headers”.
Authorization Optional. See section “HTTP Request Headers”.
HTTP Parameters
NameTypeNotes
typeEnumeration: Full, DOIKernel, SelfDefined, Simple, Provenance, AlternateIDs, LinkedAlternateIDRefer to the EIDR Registry Technical Overview for complete details. Defaults to Full. This field is case-insensitive.
formatEnumeration: json, tsvThe output data format. Defaults to JSON. This field is case-insensitive.
POST body A JSON array containing EIDR identifiers as an array of strings (see examples).
Resolution Service Request
HTTP Response Headers
NameTypeNotes
Content-typeapplication/json text/tab-separated-valuesSee section “HTTP Response Headers”.
Data
ResultsJSON or TSVReturns a JSON array of resolved IDs or a TSV header row followed by a continuous data stream of TSV records, each terminated by EndOfLine.
Resolution Service Response

Each individual record in the array is returned as per Single ID Resolution.

NOTE: Since the individual IDs are resolved in parallel, the resolutions will not necessarily be in the same order as the submitted ID list. If an error is returned, it does not follow that all prior IDs in the list are valid, only that this was the first error that the parallel resolutions returned.

Resolution Service Examples

The body of the request is a JSON object of the form:

 {ids:
   ["EIDR ID1", "EIDR ID2", …]
 } 

Below is an example of multiple ID resolution requests for DOI Kernel metadata in JSON (default) format using POST via cURL:

curl -X POST -H "Accept: application/vnd.eidr.doikernel+json" -H "Content-Type: application/json" -d '{"ids":["10.5240/7EDC-53AA-202D-6D23-666A-H", "10.5237/AD45-F060"]}' https://proxy.eidr.org/resolve

or

curl -X POST -H "Content-Type: application/json" -d '{"ids":["10.5240/7EDC-53AA-202D-6D23-666A-H", "10.5237/AD45-F060"]}' 'https://proxy.eidr.org/resolve?type=doikernel'

Here is a sample JSON response to a multiple ID resolution request for LinkedAlternateIDs:

[
   {
     "ID": "10.5240/E99A-C175-9DC2-F0CE-334F-T",
     "LinkedAlternateID": [
       {
         "AlternateID": [
           {
             "AlternateID": "5410753",
             "_type": "Baseline"
           }
         ]
       },
       {
         "AlternateID": [
           {
             "AlternateID": "403935",
             "_domain": "allocine.fr/episode",
             "_type": "Proprietary"
           }
         ]
       },
       {
         "AlternateID": [
           {
             "AlternateID": "tt0708420",
             "_relation": "IsSameAs",
             "_type": "IMDB"
           }
         ],
         "URL": {
           "URL": "http://www.imdb.com/title/tt0708420",
           "_type": "text/html"
         }
       }
     ]
   },
   {
     "ID": "10.5240/95C9-06C1-54DC-BA72-7407-D",
     "LinkedAlternateID": [
       {
         "AlternateID": [
           {
             "AlternateID": "5410783",
             "_type": "Baseline"
           }
         ]
       },
       {
         "AlternateID": [
           {
             "AlternateID": "23316",
             "_domain": "allocine.fr/episode",
             "_type": "Proprietary"
           }
         ]
       }
     ]
   }
 ]

JSON to TSV Conversion

This service converts an EIDR-compliant JSON record into an equivalent TSV (tab-separated value) record.  

NameValue                       
URLhttps://proxy.eidr.org/jsontotsv
MethodHTTP POST
EncodingNone
HTTP Headers
NameTypeNotes
Accept See section “HTTP Request Headers”.
Authorization Optional. See section “HTTP Request Headers”.
JSON to TSV Request
HTTP Response Headers
NameTypeNotes
Content-typeapplication/jsonSee section “HTTP Response Headers”.
Data
ResultsTSVReturns a TSV version of the supplied JSON record.
JSON to TSV Response

JSON to TSV Conversion Examples

Below is an example of a JSON to TSV conversion request using POST via cURL:

curl -X POST  -H "Content-Type: application/json" -d '{"data":[{"ID":"10.5240/638E-04F8-E718-C84B-85C2-N","StructuralType":"Abstraction","Mode":"Visual","ReferentType":"Short","ResourceName":{"value":"As in a Looking Glass","_lang":"en"},"OriginalLanguage":[{"value":"en","_mode":"Visual"}],"AssociatedOrg":[{"_role":"producer","DisplayName":"American Film Manufacturing Company"}],"ReleaseDate":"1911","CountryOfOrigin":["US"],"Status":"valid","ApproximateLength":"PT23M","AlternateID":[{"value":"Q2866255","_domain":"wikidata.org","_type":"Proprietary"},{"value":"20996","_domain":"citwf.com","_type":"Proprietary"},{"value":"tt0413737","_type":"IMDB"}],"Administrators":{"Registrant":"10.5237/superparty"},"Credits":{"Director":[{"DisplayName":"Allan Dwan"}],"Actor":[{"DisplayName":"J. Warren Kerrigan"}]}},{"ID":"10.5240/30EF-98BA-CAF9-F098-427A-7","StructuralType":"Abstraction","Mode":"Visual","ReferentType":"Short","ResourceName":{"value":"As in a Looking Glass","_lang":"en"},"OriginalLanguage":[{"value":"en","_mode":"Visual"}],"AssociatedOrg":[{"_role":"producer","DisplayName":"Monopol Film Company"}],"ReleaseDate":"1913","CountryOfOrigin":["US"],"Status":"valid","ApproximateLength":"PT30M","AlternateID":[{"value":"tt0413738","_relation":"IsSameAs","_type":"IMDB"},{"value":"20992","_domain":"citwf.com","_type":"Proprietary"},{"value":"Q60564935","_domain":"wikidata.org","_type":"Proprietary"}],"Administrators":{"Registrant":"10.5237/superparty"},"Credits":{"Director":[{"DisplayName":"Stanner E.V. Taylor"}],"Actor":[{"DisplayName":"Marion Leonard"}]},"RegistrantExtra":"AL:Pro;","Description":{"value":"Unclear if it was initially released with or without subtitles","_lang":"en"}}]}' https://proxy.eidr.org/jsontotsv

API Information Service

This service provides information about the API itself, including query limits and software versions.                

NameValue                       
URLhttps://proxy.eidr.org/info
MethodHTTP GET
EncodingNone
HTTP Headers
NameTypeNotes
Acceptapplication/jsonSee section “HTTP Request Headers”.
Authorization Optional. See section “HTTP Request Headers”.
API Information Service Request
HTTP Response Headers
NameTypeNotes
Content-type See section “HTTP Response Headers”.
Data
ResultsJSONSee example below.
API Information Service Response

curl -X GET -H "Content-type: application/json" 'https://proxy.eidr.org/info'

{"limits": {"idOnly": 150000,"simple": 50000,"other": 1000},"versions": {"eidrApiVersion": "2.6.0","eidrConnectorVersion": "0.0.13","eidrProxyVersion": 1.0.2"}}

Limits

Maximum query page size or maximum records returned with pageSize=0 (an un-paged query):

  • idOnly: Maximum records returned by a Query with type=idOnly
  • simple: Maximum records returned by a Query with type=simple
  • other: Maximum records returned by a Query with any type other than idOnly or simple.

Versions

Current software version numbers:

  • eidrApiVersion: EIDR registry (schema) version
  • eidrConnectorVersion: EIDR open source connector version
  • eidrProxyVersion: EIDR script (API end points and processing scripts) version

Restricted Services API Proxy

This section defines the actual HTTP headers, parameters, and data transmitted for each of the services that require EIDR API credentials.

Query services are supported using HTTP POST.

Query service

The API Proxy query service comes in two basic forms:

  • Standard EIDR XML query pass through
  • JSON query

The Query API accepts the same MIME types and Accept headers as Resolve/POST. XML requests generate an error and are not redirected.[4]

NOTE: To avoid client time-out errors, query size limits are imposed on certain query types. See “API Information Service” for the specific limits.

NameValue 
URLhttps://proxy.eidr.org/query/ 
MethodHTTP POST 
Encodingtext/xml OR application/json (see example section) 
HTTP Parameters 
NameTypeNotes 
typeEnumeration: Full, DOIKernel, SelfDefined, Simple, Provenance, AlternateIDs, LinkedAlternateIDRefer to the EIDR Registry Technical Overview for complete details. Defaults to Full. This field is case-insensitive.
formatEnumeration: json, tsvThe output data format. Defaults to JSON. This field is case-insensitive.
idOnlyBoolean: true, falseReturn only EIDR IDs. Defaults to false. If true, then type is ignored.
sortEnumeration: title, date, length, coo, struct, reftype, langSee “Query Service” above for details.
orderEnumeration: asc, descThe direction of the requested sort. Defaults to ascending.
pageNumberPositive IntegerSee EIDR REST API Reference
pageSizeNon-Negative IntegerThe EIDR registry returns paged query results. The API Proxy will manage the paged results as follows:
• If you do not specify pageSize, the query will use the default (2,500)
• If you set pageSize = 0, the query will return without paging (individual pages are cached on the proxy server until the entire query is ready to send)
• If you set pageSize to something other than a non-negative integer, you will receive an error
See EIDR REST API Reference
rootEIDR IDAn EIDR Content ID. The query will be limited to this record and its descendants.
HTTP Headers 
NameTypeNotes 
Accept See section “HTTP Request Headers”. 
Accept-Encoding See section “HTTP Request Headers”. 
Authorization See section “HTTP Request Headers”. 
HTTP POST Parameters 
NameTypeNotes 
POST body• content-type =  application/xml
• content-type = application/json
For application/xml, the POST body is a standard EIDR XPath query string
For application/json, the POST body is a JSON query, described below
 
Query Service Request
HTTP Headers
NameTypeNotes
Content-typeInternet Media Type (MIME)See section “HTTP Response Headers”.  
Data
idOnly=”false”  Application/json  A JSON object.
{
totalMatches: <total number of results for the query>, pageSize: <pageSize from the request> pageNumber: <pageNumber from the request>  results:[ <one element for each result in this response>]
}    
 Text/tab-separated-valuesRefer to the TSV column names (and sort order) in “EIDR XML Field Name Mapping Tables,” below.
idOnly=”true”Application/jsonA JSON object:
{
idOnly: true,   [“EIDR-ID-1”, “EIDR-ID-2”,…] }  
 Text/htmlThe string “EIDR_ID”,
Followed by \n (newline)
Followed by a list of newline-separated EIDR IDs.  
Query Service Response

XML Query Service Examples

The format of the response to a query request is as follows:

HTTP/1.1 200 OK

Content-Type: text/xml; charset=UTF-8

<Response goes here>

Query expressions are used when making a query with the POST method. Refer to the EIDR Registry Technical Overview for the standard EIDR XPath query expression grammar.

Below is an example of an XML pass-through query via cURL:

curl -X POST -H "Accept: application/json" -H "Content-Type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query.txt 'https://proxy.eidr.org/query?pageSize=20&pageNumber=1&sort=lang&order=desc'

Where “query.txt” is a text file containing a valid EIDR XML query. For example:

query.txt contains:

(/FullMetadata/BaseObjectData/Credits/Director/DisplayName "muybridge" AND /FullMetadata/BaseObjectData/Status "valid")

and is submitted using:

curl -X POST -H "Accept: application/json" -H "Content-Type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query.txt 'https://proxy.eidr.org/query?pageSize=20&pageNumber=1&sort=date&order=desc&type=simple'

{
    "totalMatches" : 2,
    "results" : [
       {
          "ResourceName" : {
             "_lang" : "und",
             "ResourceName" : "Homage to Eadweard Muybridge"
          },
          "Status" : "valid",
          "ReferentType" : "Short",
          "ID" : "10.5240/B0E9-0FC9-7038-6692-E5DE-P",
          "ReleaseDate" : "1994",
          "OriginalLanguage" : [
             {
                "_mode" : "Audio",
                "OriginalLanguage" : [
                   "en"
                ]
             }
          ],
          "StructuralType" : "Abstraction"
       },
       {
          "OriginalLanguage" : [
             {
                "OriginalLanguage" : [
                   "zxx"
                ],
                "_mode" : "Visual"
             }
          ],
          "StructuralType" : "Abstraction",
          "ReleaseDate" : "1878-06-15",
          "ResourceName" : {
             "_titleClass" : "release",
             "ResourceName" : "Sallie Gardner at a Gallop",
             "_lang" : "en"
          },
          "ReferentType" : "Short",
          "ID" : "10.5240/9752-46B8-CE37-64B9-C5AD-X",
          "Status" : "valid"
       }
    ]
   "pageSize": 20,
   "pageNumber": 1,
   "currentSize": 2
 }

curl -X POST -H "Content-type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query.txt 'https://proxy.eidr.org/query?format=json&idOnly=true&type=full'

{"totalMatches":2,
  "results":[
     "10.5240/B0E9-0FC9-7038-6692-E5DE-P",
     "10.5240/9752-46B8-CE37-64B9-C5AD-X"
    ],
   "idOnly":true
   "pageSize": 2500,
   "pageNumber": 1,
   "currentSize": 2
 }

curl -X POST -H "Content-type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query.txt 'https://proxy.eidr.org/query?format=tsv&idOnly=true&type=full'

EIDR_ID

10.5240/B0E9-0FC9-7038-6692-E5DE-P

10.5240/9752-46B8-CE37-64B9-C5AD-X

You can use a “rooted query” to limit the results returned. For example:

query2.txt contains:

(/FullMetadata/BaseObjectData/Credits/Director/DisplayName "kubrick" )

and is submitted using:

curl -X POST -H "Content-type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query2.txt 'https://proxy.eidr.org/query?idOnly=true&pageSize=100'

Currently returns 71 items.[5]

Adding a root restriction to the query:

curl -X POST -H "Content-type: text/xml" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d @query2.txt 'https://proxy.eidr.org/query?idOnly=true&pageSize=100&root=10.5240/5240-AEED-91B0-86C7-1CF3-7'

Will only return six items – 10.5240/5240-AEED-91B0-86C7-1CF3-7 and its descendants.

JSON Query

Simple queries involving EIDR Content ID records may be expressed directly in JSON, without using the XML pass-through.

JSON queries can use AND, OR, and NOT operators to create complex queries. AND and OR require two or more parameters. NOT only allows one parameter.  Parameter nesting is allowed. For example: AND(OR(a,NOT(b)),c,d). The key, value pairs in a parameter are automatically evaluated for equality (e.g., key = value).

NOTE: The query operators and elements are case sensitive.

Query Elements

  • Text Elements
    • id – ID (EIDR Content ID)
    • title – ResourceName
    • alttitle – AlternateResourceName
    • anytitle – ResourceName OR AlternateResourceName
    • aoid – AssociatedOrg.organizationID
    • aoname – AssociatedOrg.DisplayName
    • aoaltname – AssociatedOrg.AlternateName
    • aoanyname – AssociatedOrg.DisplayName OR AssociatedOrg.AlternateName
    • director – Credits.Director.DisplayName
    • actor – Credits.Actor.DisplayName
    • contributor – Credits.Director.DisplayName OR Credits.Actor.DisplayName
    • altid – AlternateID.value
    • altidtype – AlternateID._type
    • altiddomain – AlternateID._domain
    • coo – CountryOfOrigin
    • lang – OriginalLanguage
    • reftype – ReferentType
    • struct – StructuralType
  • Date Elements
    • date – ReleaseDate
  • Duration Elements
    • length – ApproximateLength

Boolean Operators

  • and – logical “and” operation: {and: [{expression},{expression}…]}
  • or – logical “or” operation: {or: [{expression},{expression}…]}
  • not – logical “not” operation: {not: {expression}}
  • exists – does the element exist in the record: {exists: {element}}

Text Comparisons[6]

  • words – does the element include at least one of the words in the list: {element: {words: ‘word_list’}}
  • contains – does the element include the list of words in that order: {element: {contains: ‘word_list’}}
  • exact – does the element consist of only the list of words in that order: {element: {exact: ‘word_list’}}

Date Comparisons

  • before – is the element earlier than or equal to the supplied date/year: {element: {before: date_or_year}}
  • after – is the element later than or equal to the supplied date/year: {element: {after: date_or_year}}
  • date – is the element the same as the supplied date/year: {element: {date: date_year}}

NOTE: date_or_year is either an xs:date data type or a positive four-digit integer and must be in the form of “yyyy-mm-dd” (a full date) or “yyyy” (just a year).

NOTE: If only a year is supplied, rather than a full date, then only the year portion of dates is compared.

Duration Comparisons

  • minlength – is the element at least as long as (greater than or equal to) the supplied duration: {element: {minlength: duration}}
  • maxlength – is the element no longer than (less than or equal to) the supplied duration: {element: {maxlength: duration}}
  • length – is the element exactly (equal to) the supplied duration: {element: {length: duration}}

NOTE: [duration] is an xs:duration data type and must be in the form of “PdDThHmMsS” where d, h, m, and s are the number of Days, Hours, Minutes, and Seconds; d, h, and m are non-negative integers; s is a non-negative decimal; and you trim leading and trailing zero elements: e.g., PT25M is 25 minutes.

Tree Comparisons

  • isroot – is the record at the root of a registration tree: {isroot: boolean}
  • parent – does the record have the supplied Content ID as its parent: {parent: eidr_id}

JSON Query Service Examples

JSON and XML queries return their results in exactly the same format. (See “XML Query Service Example” above.) They only differ in how the query expression is passed to the registry.

The API Proxy translates the JSON query into a standard EIDR XML query for submission to the registry, so the same conditions and limitations apply. See “Text Processing and Queries” in Registry Technical Overview.

NOTE: When using the JSON query, you must use the JSON query element names, not the XML or JSON field names. See “Query Elements,” above.

Below are examples of JSON queries via cURL:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d '{"anytitle": {"words": "star wars"}}' 'https://proxy.eidr.org/query?pageSize=60&sort=date&order=desc'

This command generates the EIDR XML query:

((/FullMetadata/BaseObjectData/ResourceName star) OR

(/FullMetadata/BaseObjectData/ResourceName wars) OR

(/FullMetadata/BaseObjectData/AlternateResourceName star) OR

(/FullMetadata/BaseObjectData/AlternateResourceName wars))

If, instead, you use “title”, this becomes:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d '{"title": {"words": "star wars"}}' 'https://proxy.eidr.org/query'

This command generates the EIDR XML query:

((/FullMetadata/BaseObjectData/ResourceName star) OR

(/FullMetadata/BaseObjectData/ResourceName wars))

If you use “contains” instead of “words”:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d '{"anytitle": {"contains": "star wars"}}' 'https://proxy.eidr.org/query?sort=date&order=desc'

This command generates the EIDR XML query:

((/FullMetadata/BaseObjectData/ResourceName "star wars") OR

(/FullMetadata/BaseObjectData/AlternateResourceName "star wars"))

To find all records that include both Winona Ryder and Johnny Depp:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Eidr YOUR:CREDENTIALS:HERE" -d '{"and": [{"actor": {"contains": "Winona Ryder"}}, {"actor": {"contains": "Johnny Depp"}}]}' 'https://proxy.eidr.org/query?pageSize=60'

This command generates the EIDR XML query:

((/FullMetadata/BaseObjectData/Credits/Actor/DisplayName "Winona Ryder") AND

(/FullMetadata/BaseObjectData/Credits/Actor/DisplayName "Johnny Depp"))

The “isroot” operator can be true or false:

  • "and":[{"isroot": true}, {"title":{"contains": "star wars"}}]} – returns all root objects with “star wars” in the title.
  • {"and":[{"isroot": false}, {"title":{"contains": "gilligan"}}]} – returns all non-root objects with “gilligan” in the title.

It can be combined with the ID query element return the root elements from a list of IDs:

  • {"and":[{"isroot": true}, {"ID": {words: "id1 id2 id2…"}} ] } – returns those records in the ID list that are root objects.

NOTE: JSON expects a Boolean value for isroot, rather than a string, so do not place true/false in quotation marks.

Below are JSON query examples and the resulting XPath equivalents.

JSON: { "title": { "words": "star wars" } }

XPath: ((/FullMetadata/BaseObjectData/ResourceName star) OR (/FullMetadata/BaseObjectData/ResourceName wars))

JSON: { "anytitle": { "words": "star wars" } }

XPath: ((/FullMetadata/BaseObjectData/ResourceName star) OR (/FullMetadata/BaseObjectData/ResourceName wars) OR (/FullMetadata/BaseObjectData/AlternateResourceName star) OR (/FullMetadata/BaseObjectData/AlternateResourceName wars))

JSON: { "and": [{"title": { "contains": "star wars" } }, { "coo": { "exact": "us" } }] }

XPath: ((/FullMetadata/BaseObjectData/ResourceName "star wars") AND (/FullMetadata/BaseObjectData/CountryOfOrigin IS "us"))

JSON: { "or": [{"title": { "contains": "star wars" } }, { "coo": { "exact": "us" } }] }

XPath: ((/FullMetadata/BaseObjectData/ResourceName "star wars") OR (/FullMetadata/BaseObjectData/CountryOfOrigin IS "us"))

JSON: { "not": { "title": { "contains": "star wars" } } }

XPath: (NOT (/FullMetadata/BaseObjectData/ResourceName "star wars"))

JSON: { "date": { "date": "2000" } }

XPath: (/FullMetadata/BaseObjectData/ReleaseDate 2000)

NOTE: In JSON queries, “date” is both a query element (ReleaseDate) and comparison operator (equal to), depending on context.

JSON: { "date": { "before": "2000" } }

XPath: (/FullMetadata/BaseObjectData/ReleaseDate <= 2000)

JSON: { "date": { "after": "2000" } }

XPath: (/FullMetadata/BaseObjectData/ReleaseDate >= 2000)

JSON: { "length": { "length": "PT23M" } }

XPath: (/FullMetadata/BaseObjectData/ApproximateLength PT23M)

NOTE: In JSON queries, “length” is both a query element (ApproximateLength) and comparison operator (equal to), depending on context.

JSON: { "length": { "maxlength": "PT23M" } }

XPath: (/FullMetadata/BaseObjectData/ApproximateLength <= PT23M)

JSON: { "length": { "minlength": "PT23M" } }

XPath: (/FullMetadata/BaseObjectData/ApproximateLength >= PT23M)

JSON: { "exists": "actor" }

XPath: (/FullMetadata/BaseObjectData/Credits/Actor/DisplayName EXISTS)

JSON: { "isroot": true }

XPath: (NOT ((/FullMetadata/ExtraObjectMetadata/SeasonInfo EXISTS) OR (/FullMetadata/ExtraObjectMetadata/ClipInfo EXISTS) OR (/FullMetadata/ExtraObjectMetadata/ManifestationInfo EXISTS) OR (/FullMetadata/ExtraObjectMetadata/EpisodeInfo EXISTS) OR (/FullMetadata/ExtraObjectMetadata/EditInfo EXISTS)))

NOTE: JSON expects a Boolean value for isroot, rather than a string, so do not place true/false in quotation marks.

JSON: { "parent": "10.5240/B6AC-E65C-3B92-CF93-8DC0-1" }

XPath: ((/FullMetadata/ExtraObjectMetadata/SeasonInfo/Parent 10.5240/75C0-4663-9D6D-C864-1D9B-I) OR (/FullMetadata/ExtraObjectMetadata/ClipInfo/Parent 10.5240/75C0-4663-9D6D-C864-1D9B-I) OR (/FullMetadata/ExtraObjectMetadata/ManifestationInfo/Parent 10.5240/75C0-4663-9D6D-C864-1D9B-I) OR (/FullMetadata/ExtraObjectMetadata/EpisodeInfo/Parent 10.5240/75C0-4663-9D6D-C864-1D9B-I) OR (/FullMetadata/ExtraObjectMetadata/EditInfo/Parent 10.5240/75C0-4663-9D6D-C864-1D9B-I))

JSON Query ERROR MESSAGES

If your query contains mismatched or missing quotes, braces, or brackets or an incorrect use of single-quotes when double-quotes are required, you will likely receive the following error message:

 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8">
     <title>Error</title>
   </head>
   <body>
     <pre>Bad Request</pre>
   </body>
 </html> 

Check your syntax, compare it to the examples above, and carefully match opening/closing quotes, braces, and brackets.

If your query returns nothing at all – no data values, no errors – then the most likely cause is that you have included an invalid keyword: e.g., “anytitles” instead of “anytitle” (the extra “s” is invalid).

NOTE: Use the cURL “-i” option to return the HTTP headers to verify that command have been received by the API Proxy server.

See Also:


[1] Redirecting to the DOI Proxy for resolution.

[2] The <asset ID> is any valid EIDR ID in the form <DOI Prefix>/<DOI Suffix>, including Content ID, Video Service ID, or Party ID.

[3] So long as all of the referenced registries support the selected resolution type (i.e., Full or DOIKernel). Any other resolution type is limited to Content IDs.

[4] The DOI Proxy only supports Resolve, so Query transactions are not redirected. You must call the standard EIDR API directly.

[5] The exact count will change as records are added to the registry.

[6] Text comparisons are subject to the standard EIDR XML restrictions. Namely, that comparisons are made token by token, after space, punctuation, and capitalization normalization. This means that you cannot perform a true substring or wildcard search. See “Text Processing and Queries” in Registry Technical Overview for more information.

Updated on April 5, 2021

Was this article helpful?

Related Articles