Search API (REST)BETA

The vLex REST search API allows developers to query vLex search engine and connect it to third-party applications.

The API is implemented in JSON over HTTP using GET methods. All methods are read-only.

Authentication

Usage of the API is always through an existing vLex user: the user can be a standard vLex user, but for corporate accounts it is recommended that a dedicated user within the corporate account is reserved for API usage.

You're required to add user credentials via HTTP Basic Authentication. For example

curl -u user:password "api.vlex.com/search.json?q=privacy&jurisdiction=CA"

Anonymous access is not allowed.

Response formats:

Two response formats are available:

• JSON: The default format for all API responses. This is recommended for server-side processing.
• JSONP: By adding a callback parameter to any URL you will obtain a JSONP response that can be processed by the user's browser javascript engine. For example, define a 'handle_vlex_results' javascript function and then add to your HTML response:

<script src="/img/spacer.gif"> 

		
The included javascript will call your 'handle_vlex_results' function with the response contents as the function argument.

		
Simple search
		
		

			
URL
			
api.vlex.com/search.json?q=SEARCH+TERMS
			
Action
			
Will perform search across all jurisdictions and content types


		
q (the search query) is the only required parameter. The following syntax is allowed in the query:
		

			
“phrase search“
		 	
[proximity search]
			
boolean operators (using any combination of “AND”, “OR”, “(“ and “)”)
		
		

		
Adding filters to the search
		

			The following filters may be added:
		
		

			

				

					

						Parameter name
					
					

						Filter Description
					
					

						Valid Values
					
				
				

					

						jurisdiction
					
					

						

							a two letter code indicating the jurisdiction being searched
						
						

					
					

						

							EA: International Law
						
						

							EU: European Union Law
						
						

							CP: Comunidad Andina Law
						
						

							For all other jurisdictions use the two letter ISO code for this country.
						
						

							For example IT for Italy.
						
					
				
				

					
content_type
					

						

							one of..
						
					
					

						

							1: News & Business
						
						

							2: Case Law
						
						

							4: Form & Contracts
						
						

							5: Legal Journals & Books
						
						

							6: Legislacion & Regulations
						
					
				
				

					
type

					
					
A filter on the type of results returned. 
					
					

						

							document: article-level results (for ex: journal articles, book chapters, caselaw decisions)
						
						

							source: source-level results (for ex: journals, books, etc.)
						
						

							topic: topic pages in vLex.com (in spanish: “voz del tesauro”)
						
						
						
More than one type can be included. Ex: type=document,source
						

							
						

					
				
			
		
		

		
Paginating results
		

			

				

					

							parameter name
					
					

							description
					
					

							valid values
					
				
				

					

							page
					
					

						

							the page to be retrieved, starting with 1 for the 1st page
						
					
					

						

							any integer
						
					
				
				

					

							per_page
					
					

						

							size of each page
						
					
					

						

							any integer up from 1 up to the maximium page size (100)
						
					
				
			
		

		

			Be aware that the actual number of results returned in the first page may be greater than the requested per_page. This is to be expected because the first page includes up to per_page document results plus a variable number of supplemental results (such as sources and topics).  
		



		
Response contents
		If successful, the response will be a json document with two elements:
		
		

			

				

					
Element Name
					
Contents
					
Example Response

				
				

					
count
					

						

							The total number of results for the query. The value returned may be the exact number of results or a lower bound; in the later case, the number will be preceded by a “>” sign.
						
						

					
					

"count" : 371
"count" : ">1000"
						

					
				
				

					
results
					
					

						

							A list of the results for the current page.
						
						

							See the “Results element” section for details
						
					
					

{"results" : [
     {
	   "title": "Responsabilidad patrimonial de la Administracion y contrato de seguro",
	   "url": "vlex.com/source/responsbilidad-patrimonial-administracion-contrato-seguro-633",
	   "id": "633",
	   "type": "source"
     },
     {
	  "title": "Ley 50/1980, de 8 de octubre, de Contrato de Seguro.\n",
	  "url": "vlex.com/vid/ley-contrato-seguro-126978?ix_resultado=1.0&query%5Bbuscable_id%5D=ES&query%5Bbuscable_type%5D=Pais&query%5Btextolibre%5D=contrato+de+seguro",
	 "id": "126978",
	 "type": "document" 
      }
]}


					
				
			
		
		
		
		
results element
		
The default response includes a minimum amount of information for each returned object: only the title, document ID, result type and URL of the document are returned.

		
For simple results a single pair title + URL is returned. For example
{
   "id" : 127560,
   "type" : 'document',
   "url" : 'vlex.com/vid/217560',
   "title" : 'Código Civil',
}
			
			
		
For compounded results (results that point to a part within a broader object) a “parent” element will be returned. For example:

{
   "id" : 127560,
   "type" : "document",
   "url" : 'vlex.com/vid/217560/node/15',
   "title" : 'Art. 15',
   "parent" : {"title" : 'Código Civil',  "url" : "vlex.com/vid/217560/"}
}

	
This is expected to be rendered as:
		
Código Civil > Art. 15

Parent relationships can be nested. For example:

{
 "parent": {
   "parent": {
     "type": "topic",
     "title": "Derecho tributario",
     "url": "vlex.com/jurisdictions/ES/search?voz_id=946988",
     "id": 946988
   },
   "title": "Tributos",
   "url": "vlex.com/jurisdictions/ES/search?voz_id=947107",
   "id": 947107,
   "type": "topic"
 },
 "title": "Impuestos",
 "url": "vlex.com/jurisdictions/ES/search?voz_id=947174",
 "id": 947174,
 "type": "topic"

}


And that would be rendered as:

	
Derecho tributario >
	Tributos >
	Impuestos
	


		
Requesting additional information: (include parameter)
		

			Additional information can be requested using the include parameter. For example:  
		
curl --user USER:PASSWORD api.vlex.com/search.json?q=privy+council&jurisdiction=CA&include=abstract,context

		The following additional elements will be added to the results if requested with the include paramater:
		
		

			

				

					

							Name
					
					

							Contents
					
					

							Example Response
					
				
				

					

							abstract
					
					

							Human generated abstract for the result, if available.
					
					

"abstract" : ‘RECURSO DE CASACIÓN. FALTA INTERÉS LEGÍTIMO PARA RECURRIR. Todos los motivos se desestiman porque están en contraste con los propios actos de los recurrentes, que conducen a una falta de legitimación para recurrir en casación. En efecto, éstos en su demanda solicitaban subsidiariamente que si se declaraba que la compraventa encubría una donación válida, se redujese. No pueden ahora impugnar que la sentencia acoja precisamente esa primera parte de la súplica de la demanda, y que se considere que no hubo donación cuando ellos partían precisamente del presupuesto contrario. Se desestima la casación.”
					
				
				

					

					snippet
					
					
A short portion of the result contents. Search terms will be highlighted with the HTML <strong> tag and the class "highlighted". 
						
					
					

"snippet": "...En consecuencia, el \u003Cstrong class=\"highlighted\"\u003Emito\u003C/strong\u003E de la inmediaci\u00f3n debe ceder ante la tutela judic...",

					
				
				

					

							context
					
					

						

							A list of of text and links (a breadcrumb) indicating the document context.
						
					
					

					
"context" : [
  {"title": "Legislación Refundida","url": "vlex.com/source/codigos-normas-refundidas-62"},
  {"title": "Normativa Estatal"}
]

This example response is expected to be rendered to the user in this order:
	

						Legislación Refundida › Normativa Estatal
						
						

						

						Note that the url field will not always be present: some of the items in the context list may not point to a specific URL in vLex.