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 "http://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=”http://api.vlex.com/search.json?q=privacy&callback=handle_vlex_results”></script>

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

Simple search

URL
http://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": "http://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": "http://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" : 'http://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" : 'http://vlex.com/vid/217560/node/15',
   "title" : 'Art. 15',
   "parent" : {"title" : 'Código Civil',  "url" : "http://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": "http://vlex.com/jurisdictions/ES/search?voz_id=946988",
     "id": 946988
   },
   "title": "Tributos",
   "url": "http://vlex.com/jurisdictions/ES/search?voz_id=947107",
   "id": 947107,
   "type": "topic"
 },
 "title": "Impuestos",
 "url": "http://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 http://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": "http://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.