EMIS API DOCUMENTATIONS
News & Reports

01 Document History

About the Data

Author Version Date Details
Ivan Zhekov 0.1 Draft 28/04/2016 Initial draft document with missing Dictionary class and Search query related error codes.
Ivan Zhekov 0.2 Draft 11/05/2016 Initial feed configuration documentation added.
Ivan Zhekov 0.3 Draft 16/05/2016 Feed configuration documentation updated. Dictionary class routines added. Updated the list of functional error codes.
Ivan Zhekov 1.0 17/05/2016 Initial public version.
Ivan Zhekov 1.1 01/06/2016 API Notification details updated.
Ivan Zhekov 1.2 19/06/2016 Added XSD/JSON schema references. Updated API functions list and their parameters. Added information about API report usage. Updated error codes.
Ivan Zhekov 1.2.1 19/06/2016 Small specification fixes.
Ivan Zhekov 1.3 15/07/2016 Namespace structure updated. Added information about the PHP SDK. Fixed endpoint links. Updated error codes.
Aron Negyesi 1.3.1 15/07/2016 Document verified. Added additional information.
Ivan Zhekov 1.3.2 15/07/2016 Added information about the search term syntax, section 'Querying'.

02 Overview

The EMIS Documents API allows retrieval of news documents and reports based on search terms and filtering criteria. The API is accessed through HTTPS and is able to return the data in both JSON and XML format. References to the related JSON / XSD schemas are provided along with this documentation. The API is function based, not following REST principles as it is intended to be used mainly for retrieving information. As such it can be queried using both POST and GET parameters. This is especially important when constructing complex queries that could be quite long and sending them with a GET request may not be compatible with certain web browsers and the underlying web server.

In order to access the API, you need to authenticate with EMIS and should have a valid EMIS API subscription.

Each API function can be identified by its class and method names. Within the document a special notation is used in order to refer other API functions in format Class/method. To specify a returned function element the notation Class/method:element is used.

In the whole EMIS database we have over 166 million news and nearly 2 million reports covering mainly emerging markets. We split our news and reports by topics to help you in finding the documents you need for your work. Currently we have 350 of them.

We are having currently approximately 40 thousand publications worldwide.

03 Result Format

The returned API answers are loosely based on the JSON API specification (http://jsonapi.org/) without pretending to follow it in details. All the answers contain either a data or errors element.

The XML presentation is following the same JSON API rules, and having RDF (Resource Description Framework) as a root element. RDF is used to indicate the document contains resource data rather than actually using any of the RDF XML specification features.

While the JSON results are using arrays for enumeration purposes, the XML presentation returns the enumerated values as a sequence of elements named item.

Element Name Description Format
data Indicates the API query has been successfully executed.
Contains the requested data.
JSON/XML
errors Indicates the API query failed. Contains details about the actual error. JSON/XML
version API Version JSON/XML
RDF Root XML element. XML
item A single element of an enumeration (array). XML
_type Describes the element is an object containing its type.
Can be used for unserialization.
JSON/XML

Error Result

When there is something wrong with an API request, the details for the actual error are returned within the errors element. Multiple errors could be returned in certain cases.

Error Codes

The API may return various of codes. Those can be classified as follows:

  • Internal API Error - 4 digit codes starting with 1. Always returns HTTP Code 500.
  • Authentication Error - 4 digit codes starting with 2 (e.g. session expired).
  • General API Error - 4 digit codes starting with 3 (e.g. missing required parameter).

Always returns HTTP Code 400.

  • Special API Errors - Any other 4 digit codes.
  • API Functional Error - 7 digit codes (e.g. validation error). Always returns HTTP Code 400.
  • Unknown Error - Error code 0. May return various HTTP Codes.

Internal API Errors

Those errors should not normally happen in a production environment. If any of them are reported, contact the API vendor.

All the internal errors return HTTP status code 500.

Code Detail
1000 API package not found.
1001 API package already defined.
1002 No package specified and no default package configured.
1020 API methods should not wrap data/error keys.
1021 API methods should not wrap data/error properties.
1022 API methods should not return json as a result.
1030 Config path and/or name not specified. Use method getConfig to initialize it.
1031 Cannot find configuration section %s specified in APPLICATION_ENV.
1032 Configuration file validation failed: %s
1033 Configuration path not found.
1034 XSD file %s not found.
1040 Unknown output format.
1050 Invalid entity manager type.

Authentication Errors

Code Http Code Detail Description
2000 401 Authentication required. Authentication is required. Possibly the provided sessionId is wrong. Try to re-authenticate and provide updated sessionId.
2001 401 Authentication error. Possibly invalid authentication credentials provided. The authentication server returned an error and the authentication cannot be completed. In most cases it's due to incorrect login credentials provided. Check whenever your username and password are correct.
2002 401 Error logging out. Error during logout.
2010 401 Authentication session expired. The authentication session is no longer valid or expired. Reauthenticate using Auth/login method.
2011 401 User data unavailable. Error retrieving user data. Try re-authenticating. If the issue persists, contact the API vendor.
2012 401 Session ID is required. sessionId is missing. Provide sessionId along with the other query parameters.
2020 403 Access restricted. Access to this functionality is restricted for all the users.
2021 403 Insufficient privileges. You don't have proper privileges to access this functionality.
2030 401 Invalid authorization type. Internal error. This functionality cannot be accessed.
2040 401 Token authentication error. You tried to reuse an authentication token as a login method, but the process failed. Try login again using username/password with Auth/login.
2050 520 Cookie file not found. Internal error. Try again. If the problem persists, contact the API vendor.
any 400 any Unknown authentication error.

General API Errors

Those API errors are common for most API function calls. Returns HTTP status code 400.

Code Detail Description
3000 API method not specified. An API call is performed, but the API method is not specified.
3001 Remote calling of the class constructor is not allowed. An attempt was made to call a restricted constructor method.
3002 Missing parameter: %s A required parameter is not provided.

Special Errors

Code Description
8000 An error has been forwarded from the backend. Check the error's detail field for additional information.
8001 Error accessing backend URL. Contact the API vendor.
9000 An unknown HTTP code received from the backend. Check the error's detail field for additional information.

04 Class Auth

API functions used for authentication purposes

Auth/login - Authentication

Authentication is required before executing any protected API call. The authentication is performed by passing a username and password pair. On a successful call, a sessionId is provided. The sessionId is a token identifying the current authentication session and have to be provided as a GET/POST parameter with each next API call.

Endpoint Details

  • Class - Auth
  • Method - login
  • JSON Endpoint URL - https://api.emis.com/news/Auth/login/
  • XML Endpoint URL - https://api.emis.com/news/xml/Auth/login/

Example Response

{
data: {
userId: "example-account",
authSession: "201604281122561461842576example-account",
authDigest: null,
profileId: null,
tokenSignature:
"SUstRlqNd2HfeAcmA5LObF5re4cLtCHeepAqHIfkpejndX8u9RLl1K0dcF2C70X0uXM2kRXZW+LQIaXvpJhdojQaaQX9+c1a
LRFtVlf2YFrnMdakDiIfEaigkdJTlt6jYxy779U79IKqSj+yO3MRlje0cFjJOLXK6ztSfkmZKmkwn1jHN+2BlgO9LIWQT0dxQNCnn
f3WSC9XrP9Ix5qmVJV9pbMBNfunqL+0492woctAWXOMhc5htW440/+sLxRcxUkZeX8kAGwmUj9tNQDclYdPMfzoGV1pTp
6hSagW75sChDJ64KSEm4CgdW115kN11etXO6/TjqcsSdR5jnncTg==",
tokenTimestamp: "1461831261",
tokenUsername: "example-account",
sessionId: "e4f18e132f86683cdf8a127f8fe0bca2"
},
version: "dev"
}
                    

Request Parameters

Name Description Type Accepted values Required
username API account username String Y
password API account password String Y

Response Fields

Name Description Type
userId Username used for login. String
authSession Internal use only. String
authDigest Internal use only. String
profileId User profile ID. Not relevant for most API users. Integer
tokenSignature A digital signature that can be used for re-authentication without sending the username/password using loginToken method. String
tokenTimestamp Used along with tokenSignature. Integer
sessionId Token to be used with all the consequential queries. The value of the token have to be passed as a GET/POST parameter with any API query requiring authentication. String

Auth/logout - Logout

For short lived API sessions it is recommended to perform a logout operation. This will ensure the generated sessionId token cannot be reused and that it won't consume a license (if such restriction is applied for the specific user account).

Endpoint Details

  • Class - Auth
  • Method - logout
  • JSON Endpoint URL - https://api.emis.com/news/Auth/logout/
  • XML Endpoint URL - https://api.emis.com/news/xml/Auth/logout/

Example Result

{
data: [ ],
version: "dev"
}

Request Parameters

Name Description Type Accepted values Required
sessionId Session ID token to logout. String Y

Response Fields

On success an empty element is returned.

Auth/tokenLogin - Token Authentication

A token authentication is a special type of authentication that can be performed without specifying the account's password. A special digital signature token is required for this type of authentication process. In order to retrieve a signature token, the Auth/login still have to be used. Once retrieved it can be reused multiple times, even after closing the existing session by invoking Auth/logout.

Endpoint Details

  • Class - Auth
  • Method - tokenLogin
  • JSON Endpoint URL - https://api.emis.com/news/Auth/loginToken/
  • XML Endpoint URL - https://api.emis.com/news/xml/Auth/loginToken/

Example Result

{
data: {
userId: "example-account",
authSession: "201604281155151461844515example-account",
authDigest: null,
profileId: null,
tokenSignature: null,
tokenTimestamp: null,
tokenUsername: null,
sessionId: "d095c07fa937b603a692b3c26b498fa7"
},
version: "dev"
}

Request Parameters

Name Description Type Accepted values Required
username Account's username. String Y
token The authentication sigunature token retrieved from Auth/login:tokenSignature. String Y
timestamp The authentication timestamp retrieved from Auth/login:tokenTimestamp. Integer Y

Response Fields

Name Description Type
userId Username used for login. String
authSession Internal use only. String
authDigest Internal use only. String
profileId User profile ID. Not relevant for most API users. Integer
tokenSignature Null is always returned with this method. String
tokenTimestamp Null is always returned with this method. Integer
sessionId Token to be used with all the consequential queries. The value of the token have to be passed as a GET/POST parameter with any API query requiring authentication. String

05 Class Search

Search/query - Search query

A search query is performed in order to retrieve search results containing news and reports documents based on certain search criteria.

Endpoint Details

  • Class - Search
  • Method - query
  • JSON Endpoint URL - https://api.emis.com/news/Search/query/
  • XML Endpoint URL - https://api.emis.com/news/xml/Search/query/

Example Response

{
data: {
_type: "Emis\Entity\Api\Do cumen t\R esul t",
search: {
_type: "Emis\Entity\Api\Docum en t\Search",
countries: [
"BG",
"PL"
],
formats: [
"1"
],
languages: [
"en"
],
companies: [ ],
industries: [
"54"
],
topics: [
"25"
],
sourceTypes: [ ],
publications: [ ],
startDate: {
_type: "DateTime",
date: "2015-04-28T12:34:06+00:00"
},
endDate: null,
term: null,
offset: 0,
limit: 1,
order: "newest"
},
total: 1115,
duplicates: 0,
results: 1,
documents: [
{
_type: "Emis\Entity\Api \Docum ent\Document",
id: 528887924,
title: "Bulgaria parliament passes amendments to Election Code at 2nd reading (ROUNDUP)",
language: "en",
body: "",
date: {
_type: "DateTime",
date: "2016-04-28T06:29: 33 +00:00"
},
updateDate: {
_type: "DateTime",
date: "2016-04-28T03:49: 03 +00: 00"
},
format: "HTML",
companies: [ ],
countries: [
{
_type: "Emis\Entity\Api\Di ctionar y\ Country",
id: 214,
code: "BG",
name: "Bulgaria"
}
],
topics: [
{
_type: "Emis\Entity\Api\Di ctionar y\Topic ",
id: 23,
name: "Political"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Topic ",
id: 2301,
name: "Parliament and Congress"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Topic ",
id: 2303,
name: "Political Parties/Union Parties and Syndicates"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Topic ",
id: 2304,
name: "Elections"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Topic ",
id: 25,
name: "Industry"
}
],
industries: [
{
_type: "Emis\Entity\Api\Di ctionar y\Indus try",
id: 54,
name: "Professional, Scientific, and Technical Services"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Indus try",
id: 541,
name: "Professional, Scientific, and Technical Services"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Indus try",
id: 5418,
name: "Advertising, Public Relations, and Related Services"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Indus try",
id: 92,
name: "Public Administration"
},
{
_type: "Emis\Entity\Api\Di ctionar y\Indus try",
id: 921,
name: "Executive, Legislative, and Other General Government Support"
}
],
sourceType: {
_type: "Emis\Entity\Api\Diction ary\ SourceTyp e",
id: 1,
code: "ST01",
name: "Newswires / News Agencies"
},
publication: {
_type: "Emis\Entity\Api\Diction ary\ Publication",
id: "16923",
code: "FOCUS_NEWS",
name: "Focus News - SEE"
},
files: [ ]
}
]
},
version: "dev"
}
                    

Request Parameters

Name Description Type Accepted values Required / Default
countries A list of 2 letter country codes. Array of String Dictionary / getCountries Y
formats Document formats Array of Integer 1 - HTML
2 - PDF
3 - Word
4 - Excel
Dictionary / getFormats
[1, 2, 3, 4]
languages A list of 2 letter language codes. Array of String Dictionary / getLanguages N
companies A list of company IDs. Array of Integer N
industries A list of NAICS industry codes. Array of Integer Dictionary / getIndustries N
topics A list of topics. Array of Integer Dictionary / getTopics N
sourceTypes A list of source types. Both string code and ID can be specified. Array of String | Integer Dictionary / getSourceTypes N
publicationTypes A list of publication type codes. Array of String Dictionary / publicationTypes Subscription based
publications A list of publications. Both string code and ID can be specified. Array of String | Integer Dictionary / getPublications N
startDate Query start date. ISO DateTime ISO 8601 formatted One week ago
endDate Query end date. ISO DateTime ISO 8601 formatted N
term Search term. String N
scope Search term scope. String title | everywhere everywhere
offset Offset of the search result. Integer 0
limit Maximum number of records to be returned. Integer 25
order Sort order. String newest | oldest | relevance Newest
skipDuplicates If true, skip any documents within the current page that are considered 'duplicated'. Boolean true | false true
includeBody If true, include the document body content within the search results. Boolean true | false false

Response Fields

Contains a single object of type Emis\Entity\Api\Document\Result.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Document_Result

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Document_Result

Search/getDocuments - Get document details

The method will return one or more documents specified by their Document ID along with their HTML Body.

Endpoint Details

  • Class - Search
  • Method - getDocuments
  • JSON Endpoint URL - https://api.emis.com/news/Search/getDocuments/
  • XML Endpoint URL - https://api.emis.com/news/xml/Search/getDocuments/

Example Response

{
data: {
_type: "Emis\Entity\Api\Do cumen t\R esul t",
search: {
_type: "Emis\Entity\Api\Docum en t\Documen tSearch",
ids: [
"528958003"
]
},
total: 1,
duplicates: 0,
results: 1,
documents: [
{
_type: "Emis\Entity\Api \Docum ent\Document",
id: 528958003,
title: "Exchange - Rates",
language: "en",
body: "Sofia, April 28 (BTA) - The Bulgarian National Bank sets the rates of foreign currencies against the Bulgarian lev applicable from 5 p.m.
on April 28 to 5 p.m. on May 2, 2016. The central rates are used for the purposes of accounting, statistics, customs valuation and remittances. The
commercial banks set the exchange rates at which foreign exchange is bought and sold.
______________ ___ __ ___ ___ __ ___ ___ __ ___ ___ __ ___ ___ __ ___ ___ __ ___ ___ __ ___ ___ 

CURR ENCY SWIFT CODE FOR LEVA Australian Dollar AUD 1 1.31211 Brazilian Real L 10 4.90097 Canadian Dollar CAD 1 1.37136 Swiss Franc CHF 1 1.78224 Chinese Yuan Renminbi CNY 10 2.65875 Czech Koruna CZK 100 7.23176 Danish Krone DKK 10 2.62767 British Pound GBP 1 2.51269 Hong Kong Dollar HKD 10 2.21973 Croatian Kuna HRK 10 2.61475 Hungarian Forint HUF 1000 6.29491 Indonesian Rupiah IDR 10000 1.30587 New Israel Shekel ILS 10 4.58072 Indian Rupee INR 100 2.58944 Icelandic Krona * ISK Japanese Yen JPY 100 1.59218 South Korean Won KRW 1000 1.50966 Mexican Peso MXN 100 9.94256 Malaysian Ringgit R 10 4.41985 Norwegian Krone NOK 10 2.11533 New Zealand Dollar NZD 1 1.20085 Philippine Peso PHP 100 3.66886 Polish Zloty P 10 4.45722 New Romanian Leu RON 10 4.37321 Russian Rouble RUB 100 2.66029 Swedish Krona SEK 10 2.13139 Singaporean Dollar SGD 1 1.28058 Thai Baht THB 100 4.91365 New Turkish Lira TRY 10 6.11904 US Dollar USD 1 1.72198 South African Rand ZAR 10 1.19749 Gold (1 troy ounce) XAU 1 2,164.02

", date: { _type: "DateTime", date: "2016-04-28T16:37:01+00:00" }, updateDate: { _type: "DateTime", date: "2016-04-28T13:44:34+00:00" }, format: "HTML", companies: [ ], countries: [ { _type: "Emis\Entity\Api\Dictionary\Country", id: 214, code: "BG", name: "Bulgaria" } ], topics: [ { _type: "Emis\Entity\Api\Dictionary\Topic", id: 26, name: "Financial Markets" }, { _type: "Emis\Entity\Api\Dictionary\Topic", id: 2605, name: "Foreign Exchange and Money Markets" }, { _type: "Emis\Entity\Api\Dictionary\Topic", id: 28, name: "Economic" }, { _type: "Emis\Entity\Api\Dictionary\Topic", id: 2810, name: "Exchange rate" } ], industries: [ ], sourceType: { _type: "Emis\Entity\Api\Dictionary\SourceType", id: 1, code: "ST01", name: "Newswires / News Agencies" }, publication: { _type: "Emis\Entity\Api\Dictionary\Publication", id: "12507", code: "BTA_NEWSEN", name: "BTA English Service " }, files: [ ] } ] }, version: "dev" }

Request Parameters

Name Description Type Accepted values Required
ids List of document IDs. Array of String Y

Response Fields

On success returns an Emis\Entity\Api\Document\Result object containing one or more documents along with their document body.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Document_Result

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Document_Result

Search/getFile - Retrieve a binary file

This method retrieves binary files. To get the links for document downloads Search/query or Search/getDocuments have to be used.

Endpoint Details

  • Class - Search
  • Method - getFile
  • JSON Endpoint URL - https://api.emis.com/news/Search/getFile/
  • XML Endpoint URL - https://api.emis.com/news/xml/Search/getFile/

Request Parameters

Name Description Type Accepted values Required
key File identifying key. String Y

Response Fields

On success downloads the requested file.

Functional Error Codes

Code Detail
1001001 Document not found
1001002 One or more document IDs were not found
1001003 Maximum of %s documents can be requested at once
1002001 Document format not allowed: %s
1002002 Language not allowed for selected country: %s
1002003 At least one country is required
1002004 User have no any active subscriptions
1002005 User not subscribed for selected country: %s
1002006 Invalid company ID: %s
1002007 Invalid industry ID: %s
1002008 No such industry: %s
1002009 Unknown topic: %s
1002010 Unknown source type ID: %s
1002011 Unknown source type code: %s
1002012 Unknown publication ID: %s
1002013 Unknown publication code: %s
1002014 The offset must be an integer
1002015 The offset cannot be negative
1002016 The limit must be an integer
1002017 The limit must have a positive value
1002018 Maximum of %s results allowed per page
1002019 Invalid sort order. Valid values: %s
1002020 Publication type %s not allowed.
1002021 Invalid scope.
1003001 Executed %s requests in %s seconds. Limit reached.
1004001 Using News API requires APID submodule.

06 Class Dictionary

Dictionary/getCountries

Returns a list of countries and their codes.

Endpoint Details

  • Class - Dictionary
  • Method - getCountries
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getCountries/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getCountries/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\Country",
id: 1283,
code: "AF",
name: "Afghanistan"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dictionary\Language entries is returned.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Language%5B%5D

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Language%5B%5Dt

Dictionary/getLanguages

Returns a list of languages and their codes.

Endpoint Details

  • Class - Dictionary
  • Method - getLanguages
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getLanguages/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getLanguages/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\Language",
code: "en",
name: "English"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dictionary\Language entries is returned.

JSON Schema:

https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Language%5B%5D

XSD Schema:

https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Language%5B%5D

Dictionary/getFormats

Returns a list of available document formats.

Endpoint Details

  • Class - Dictionary
  • Method - getFormats
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getFormats/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getFormats/

Example Response

{
data: {
HTML: 1,
PDF: 2,
WORD: 3,
EXCEL: 4
},
version: "dev"
}
                    

Response Fields

List of available formats and their index values.

Dictionary/getIndustries

Returns a list of industries along with their NAICS codes.

Endpoint Details

  • Class - Dictionary
  • Method - getIndustries
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getIndustries/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getIndustries/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\Industry",
id: "11",
name: "Agriculture, Forestry, Fishing and Hunting"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dictionary\Industry entries is returned.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Industry%5B%5D

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Industry%5B%5D

Dictionary/getPublicationTypes

Returns a list of Publication Types along with their codes.

Endpoint Details

  • Class - Dictionary
  • Method - getPublicationTypes
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getPublicationTypes/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getPublicationTypes/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\PublicationType",
id: 758,
code: "TM",
name: "Macro Indicators and Monetary Data"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dinctionary\PublicationType entries is returned.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_PublicationType%5B%5D

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_PublicationType%5B%5D

Dictionary/getSourceTypes

Returns a list of Source Types along with their codes.

Endpoint Details

  • Class - Dictionary
  • Method - getSourceTypes
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getSourceTypes/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getSourceTypes/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\SourceType",
id: 106,
code: "ST09",
name: "Chambers / Associations"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dictionary\SourceType entries is returned.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_SourceType%5B%5D

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_SourceType%5B%5D

Dictionary/getTopics

Returns a list of Topics along with their codes.

Endpoint Details

  • Class - Dictionary
  • Method - getTopics
  • JSON Endpoint URL - https://api.emis.com/news/Dictionary/getTopics/
  • XML Endpoint URL - https://api.emis.com/news/xml/Dictionary/getTopics/

Example Response

{
data: [
{
_type: "Emis\Entity\Api\Dictionary\Topic",
id: 100,
name: 'Politics"
}
],
version: "dev"
}
                    

Response Fields

An array of Emis\Entity\Api\Dictionary\Topic entries is returned.
JSON Schema:
https://api.emis.com/news/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Topic%5B%5D

XSD Schema:
https://api.emis.com/news/xml/model/Schema/getSchema/?schema=Emis_Entity_Api_Dictionary_Topic%5B%5D

07 Class Usage

This class contains functionality for reporting of document usage. The API subscribers are obligated to send reports of the documents used even they're stored and re-indexed offline at the subscriber's premises. The usage reports can be sent immediately when a usage event occurs by using Usage/report API method which will register a single document hit, or on a regular basis (e.g. once per month) sending a batch of usage reports through Usage/reportMultiple API method.
A usage event is considered when an end-user access the document, opening it for reading or downloading it.

Usage/report

Returns a list of Topics along with their codes.

Endpoint Details

  • Class - Usage
  • Method - report
  • JSON Endpoint URL - https://api.emis.com/news/Usage/report/
  • XML Endpoint URL - https://api.emis.com/news/xml/Usage/report/

Example Response

{
data: true,
version: "dev"
}
                    

Request Parameters

Name Description Type Accepted values Required / Default
documentId Document's ID for which usage will be reported. Integer Y
accessTime The exact time at which the document has been accessed. It could be different from the current, reporting time. DateTime ISO 8601 formatted Y

Response

Returns true on success or an error on failure.

Usage/reportMultiple

Returns a list of Topics along with their codes.

Endpoint Details

  • Class - Usage
  • Method - reportMultiple
  • JSON Endpoint URL - https://api.emis.com/news/Usage/reportMultiple/
  • XML Endpoint URL - https://api.emis.com/news/xml/Usage/reportMultiple/

Example Response

{
data: true,
version: "dev"
}
                    

Request Parameters

Name Description Type Required
data A URL encoded XML/JSON represented object, containing list of reported document. Emis\Entity\Api\UsageReport\Request Y

To properly construct the Request object, refer to:

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_UsageReport_Request

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_UsageReport_Request

Functional Error Codes

Code Detail
1005001 General error recording the usage report.
1005002 Invalid request format. Check schema.

08 Result Objects

The resulted data may contain different kind of objects. The object type can be identified from the _type element it contains. It can be used for creating unserialized data models. Object information within this document may not be up to date. As such always refer the provided online XSD / JSON schemas.

Emis\Entity\Api\Document\Result

Name Description Type
search Query search object. Emis\Entity\Api\Document\Search
total Total number of records for this query. Integer
duplicates Number of duplicated (skipped) results. Integer
results Number of results returned by this query. Integer
documents A list of document objects. Array of Emis\Entity\Api\Document\Document

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Result

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Result

Emis\Entity\Api\Document\Search

Name Description Type
countries A list of country codes. Array of String
formats Document formats. Array of Integer
languages A list of 2 letter language codes. Array of String
companies A list of company IDs. Array of Integer
industries A list of EMIS industry codes based on NAICS. Array of Integer
topics A list of topics. Array of Integer
sourceTypes A list of source types. Both string code and ID can be specified. Array of String | Integer
publicationTypes A list of publication type codes. It describes the type of content displayed in the service on different pages. Generally, we use three main types: News, Research and Company information Array of String
publications A list of publications. Both string code and ID can be specified. It describes the source from where the content is being provided. Array of String | Integer
startDate Query start date. ISO DateTime
endDate Query end date. ISO DateTime
term Search term. String
offset Offset of the search result. Integer
limit Maximum number of records to be returned. Integer
order Sort order. String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Search

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Search

Emis\Entity\Api\Document\Document

Name Description Type
id Document ID. Can be used with Search/getDocuments to retrieve its body. Integer
title Document's Title. String
language Document's language. Emis\Entity\Api\Dictionary\Language
body Document's body. Can have empty value for when used with Search/query or the document format is not HTML. String
date Document's date. DateTime
updateDate The date the document was last updated. DateTime
format Document's format. String
companies List of related to this document company objects. Array of Emis\Entity\Api\Dictionary\Company
countries List of relevant countries. Array of Emis\Entity\Api\Dictionary\Country
topics List of related to this document topic objects. Array of Emis\Entity\Api\Dictionary\Topic
industries List of related to this document industry objects. Array of Emis\Entity\Api\Dictionary\Industry
sourceTypes List of related to this document source type objects. Array of Emis\Entity\Api\Dictionary\SourceType
publicationTypes List of related to this document publication type objects. Array of Emis\Entity\Api\Dictionary\PublicationType
publication Related to this document publication object. Emis\Entity\Api\Dictionary\Publication
files List of file objects containing download links. Array of Emis\Entity\Api\Document\File

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Document

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Document_Document

Emis\Entity\Api\Dictionary\Company

Name Description Type
id Company ID Integer
name Company Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Company

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Company

Emis\Entity\Api\Dictionary\Country

Name Description Type
id Country ID Integer
code Country Code String
name Country Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Country

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Country

Emis\Entity\Api\Dictionary\Language

Name Description Type
code Language Code String
name Language Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Language

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Language

Emis\Entity\Api\Dictionary\Topic

Name Description Type
id Topic ID Integer
name Topic Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Topic

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Topic

Emis\Entity\Api\Dictionary\Industry

Name Description Type
id Industry NAICS Code Integer
name Country Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Industry

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Industry

Emis\Entity\Api\Dictionary\SourceType

Name Description Type
id Source Type ID Integer
code Source Type Code String
name Source Type Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_SourceType

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_SourceType

Emis\Entity\Api\Dictionary\Publication

Name Description Type
id Publication ID Integer
code Publication Code String
name Publication Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Publication

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_Publication

Emis\Entity\Api\Document\File

Name Description Type
title File's title. String
link API link to retrieve the file. The sessionId still have to be appended in order to be able to download it. String
format The file format. String

JSON:

XSD:

Emis\Entity\Api\Dictionary\PublicationType

Name Description Type
id Publication Type ID Integer
Code Publication Type Code String
Name Publication Type Name String

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_PublicationType

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_Dictionary_PublicationType

Emis\Entity\Api\UsageReport\Request

Name Description Type
documents List of documents for which usage is reported. Emis\Entity\Api\UsageReport\Document

JSON:
https://api.emis.com/news/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_UsageReport_Request

XSD:
https://api.emis.com/news/xml/model/Schema/getObjectSchema/?schema=Emis_Entity_Api_UsageReport_Request

Emis\Entity\Api\UsageReport\Document

Name Description Type
documentId Document's ID for which usage will be reported. Integer accessTime The exact time at which the document has been accessed. It could be different from the current, reporting time. DateTime (ISO 8601 formatted)

09 Querying

When executing a search query various approaches could be used to retrieve the necessary data through a combination of search terms and filtering rules. The search term is specified as a free text, while the filtering rules are applied through a set of query parameters: countries, industries, languages, publication types, topics, etc.

Search Modes

Approach Description Example
Exact Match & wildcard only Traditional approach without word stemming. Each word is searched in its entirety. Wildcard searches and exact matches could be performed.
  • "investment options" - search the phrase as-is
  • Investment AND options - search both words exactly
  • investment* - search all words starting with "investment"
  • "invest* option" - search all phrases where words starting with 'invest' are immediately before word 'option'
Combined Stemming and Exact Match and wildcard Stemming by default for standalone words without double quotes. Words will be stemmed and searched for. Words or phrases in double quotes will be searched exactly. Wildcard terms will always search the non-stemmed field. Stemming is not available for multilanguage searches, Turkish and Hungarian languages.
  • telecom AND "banking" - search stem of "telecom" but search for "banking" exactly
  • telecommunications OR investment OR banking - search all words stemmed
  • telecom* AND bank and "India" - uses wildcard, stemming and exact match
  • "Telecom service" - return exact match even in phrase search, as quotes are used
Meta only searches (using filtering criteria) Many queries will only filter on a list of fields with no related keyword. These generally are used to navigate the UI.
    Look for Telecom industry news:
  • countries - ['IN']
  • industries - ['517']
  • publicationTypes - ['TN']

Search Operators

The following case sensitive operators are supported: AND, OR, NOT, NEAR and ().

NEAR can only be applied between stemmed words or non-stemmed words.

For example:

  • incorrect: banking NEAR "wireless"
  • correct: banking NEAR wireless
  • correct: "banking" NEAR "wireless"

The order of words connected by NEAR operators should be interchangeable.

Example: bank NEAR invest NEAR phone is the same as - invest NEAR phone NEAR bank (and any other combination).

Adding a number N after NEAR as a suffix, means that the two words should have no more than N words between them, e.g. NEAR7.

Search Syntax

Search requests to the API are parsed against a query transformation service prior to hitting the search index. The query transformation layer is designed to interpret specific query syntax.

[(] term1 [{AND|OR|NOT|NEAR}] term2 [)] [[{AND|OR|NOT|NEAR}] [(] term3 [)] [[{AND|OR|NOT|NEAR} ... termN [)]]]

  • Terms can be enclosed in double quotes to indicate exact search or proximity.
  • Terms can be followed by "*" indicating a wildcard.
  • "?" in a word substitutes for one character of any kind.
  • as a part of a word the following special characters might be used: ', $, ?, /, %, _, -, +, &

Query Result

The search terms passed to the API are used to search either within the document's title or in both the title and the body. This behavior is controlled by the "scope" parameter that accepts two modes: "everywhere" and "title".

When a search term is used the words identified from it will be highlighted using HTML tags.

The returned result may include the document body or the metadata only. This is controlled through the includeBody parameter.

Based on certain rules, documents that are considered duplicates could be skipped using skipDuplicates parameter. This works only within the scope of currently returned window of documents limited by the limit parameter.

Language and Character Handling

  • Language native characters are interpreted and transferred correctly.
  • All Foreign versions of ' (double quote) characters are acceptable as double quote.
  • Character folding: Characters are understood in their transliterated/folded versions where appropriate, so words without diacritical marks and accents should search the versions with diacritics/accents.
  • Special characters are searchable as part of words such as: ', $, ?, /, %, _, -, +, &
  • Word separator '-' is treated as a space, e.g. if you search for e-commerce you will get ecommerce and e-commerce in the results.
  • All text is searchable including standalone numbers. Exceptions are special characters and words used for boolean search (e.g. AND, OR etc.)
  • Operators are accepted both in upper and lowercase, e.g. AND/OR/NOT/NEAR or and/or/not/near
  • Stemming is not used in Hungarian, Turkish and multi-language searches.

Sort Ordering

Relevance Scoring

The search parameter "order" set as "relevance".

  • Matches in the title and the abstract, short version of the body will score higher than matches in the actual body.
  • Higher number of a terms matched in the article increases relevance.
  • Shorter length articles with same number of terms are more relevant.

Date Order

The search parameter "order" with values of "newest" or "oldest". In this ordering option documents are ordered by date ascending or descending followed by relevance.

10 API SDK for PHP

EMIS API SDK for PHP provides an easy way to quickly access the needed information in an object oriented way with a minimum or no actual knowledge about the actual API protocol.

The SDK is available for download at GitHub and is also available as a Packagist package for direct installation through Composer.

GitHub Project Page: https://packagist.org/packages/php-api-client

Composer Package: https://packagist.org/packages/php-api-client

Installation

The easiest and recommended way to install the SDK is by using Composer.

composer require emis/php-api-client

Once the required package is included, all the classes will be automatically become available just by including the composer's autoloader.

require('vendor/autoload.php');

Initialization and login/logout

As a minimum your script should login/logout to EMIS API. And instance of Emis\Http\Client have to be created and login method used.

use Emis\Http\Client;

$client = new Client();
$client->login('username', 'password');

$client->logout();

Reusing sessions and bootstrapping

It's much better if your script handles a permanent session rather than login/logout on each request. You should store the generated by the login session token and then reuse it on next requests. Logout should not be performed in this case as it will destroy the current session and you won't be able to reuse the token. Tokens are expiring on daily basis. Below you can find an example that stores the current session in the filesystem, but using memcache or APC would be better for production use. We could create a bootstrap.php file that include all of this.

<?php
require('vendor/autoload.php');
if (file_exists('token.txt')) {
$token = file_get_contents('token.txt');
}
$client = new Client();
if (!$token) {
$client->login('username', 'password');
file_put_contents('token.txt', $client->getToken());
} else {
$client->setToken($token);
}
return $client 
?>

Sending API Requests

API requests are made through a set of proxy classes you could find under Emis\Document\Api\Proxy namespace. A simple example printing the document titles for country code 'HU'.

<?php
use Emis\Document\Api\Proxy\Search;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$search = new Search($client);
$result = $search->query('HU');
foreach ($result->getDocuments() as $document) {
echo $document->getTitle() . "\n";
} 
?>

Using searchQuery

The 'query' methods receives a long list of parameters. This may cause issues especially when the search parameter you'd like to use as at the end of the list. For those kind of queries it's better to use method 'searchQuery' which receives an object as input parameter. The example code below searches for Russian documents in both English and Russian language and then counts them.

<?php
use Emis\Document\Api\Proxy\Search;
use Emis\Entity\Api\Document\Search as SearchRequest;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$search = new Search($client);
$searchRequest = new SearchRequest();
$searchRequest->setCountries(array('RU'));
$searchRequest->setLanguages(array('en', 'ru'));
$result = $search->searchQuery($searchRequest);
$counter = array('en' => 0, 'ru' => 0);
foreach ($result->getDocuments() as $document) {
$counter[$document->getLanguage()->getCode()]++;
}
printf("Total of %s en documents found.\n", $counter['en']);
printf("Total of %s ru documents found.\n", $counter['ru']);
?>

Using getDocuments

The method 'getDocuments' can be used to retrieve information about a specific document for which you already have its unique ID.

The example below makes a search query using 'query' method and then retrieves the document bodies one by one through using 'getDocuments'.

<?php
use Emis\Document\Api\Proxy\Search;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$search = new Search($client);
$result = $search->query('HU');
foreach ($result->getDocuments() as $document) {
$subResult = $search->getDocuments($document->getId());
foreach ($subResult->getDocuments() as $subDocument) {
echo $subDocument->getTitle() . "\n";
}
}
?>

Dictionaries

There is a set of dictionary methods returning different kind of lists - countries, languages, industries, etc. Those lists are retrieved using class Dictionary.

The example below retrieves the list of countries and prints their codes and names.

<?php
use Emis\Document\Api\Proxy\Dictionary;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$dictionary = new Dictionary($client);
foreach ($dictionary->getCountries() as $country) {
echo $country->getCode() . " : " . $country->getName() . "\n";
}
?>

Usage Tracking

Usage tracking is required when you hold and/or index EMIS documents locally. In those cases you're responsible for reporting any document usage directly through the API. The usage can be reported immediately when the actual event happens, or in batches (e.g. each day or at the end of each month). Usage tracking is done using an instance of class Usage.

Single Document Reporting

To report usage for a single document use method 'report' as shown below, which sends a usage report for the first document retrieved in a search query.

<?php
use Emis\Document\Api\Proxy\Search;
use Emis\Document\Api\Proxy\Usage;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$search = new Search($client);
$result = $search->query('HU');
$documents = $result->getDocuments();
$usage = new Usage($client);
$usage->report($documents[0]->getId(), new \DateTime());
?>

Mutiple Documents Reporting

To report usage for multiple documents at once, you have to prepare the list of those documents using an instance of class Emis\Entity\Api\UsageReport\Request, and providing the actual access time as an additional detail. Finally the report is send using method 'reportMultiple'.

<?php
use Emis\Document\Api\Proxy\Search;
use Emis\Document\Api\Proxy\Usage;
use Emis\Entity\Api\UsageReport\Document as ReportDocument;
use Emis\Entity\Api\UsageReport\Request as UsageRequest;
/* @var $client \Emis\Http\Client */
$client = require_once('bootstrap.php');
$search = new Search($client);
$result = $search->query('HU');
$usage = new Usage($client);
$request = new UsageRequest();
foreach ($result->getDocuments() as $document) {
$reportDocument = new ReportDocument();
$reportDocument->setDocumentId($document->getId());
$reportDocument->setAccessTime(new \DateTime());
$request->addDocument($reportDocument);
}
$usage->reportMultiple($request);
?>

11 API Feed

The API Feed is a special way to receive news documents based on a preconfigured search query. The documents are generated offline on a predefined interval and then delivered through a local or remote FTP server, or using an HTTP API notification.

Feed Configuration

The API Feed can be configured through a simple web interface. Once the configuration is complete the user will start receiving feeds within the time interval specified.

Feed Configuration URL: http://www.emis.com/php/api_user

General

Configuration Parameter Accepted Values Mandatory Description
Activate Feed Checked,
Unchecked
Y Enable/Disable the feed generation and delivery.
Frequency 15, 60 Y Frequency of feed generation in minutes.
Delivery Method Local FTP, Remote FTP,
API Notification
Y Feed delivery method. See notes below.
Output Format XML, JSON Y Feed output format.

Delivery Methods

Local FTP - The feed will be delivered at a local EMIS FTP server.

Remote FTP The feed will be delivered to a remote, customer FTP server. See FTP Settings for details.

API Notification - Once a new feed is generated the user will be notified by sending an HTTP API Notification containing a personalized link to download the requested feed data.

Search Filter

If a specific filter value is not set, the resulted data won't be filtered by this criteria.

Configuration Parameter Accepted Values Mandatory Description
Search Location In all content
In title
Y Where the to look for the search term specified.
Search Term   N Search term or keyword.
Countries   Y Countries about which the feed will be generated. At least one country have to be selected.
Languages   N Languages filter.
Formats HTML, PDF, WORD, EXCEL N Document format filter.
Industries   N Industries filter.
Publication Types   N Publication type filter.
Sources   N Sources filter.
Topics   N Topics filter.

FTP Settings

The FTP settings are available when Remote FTP is selected as delivery method.

Configuration Parameter Accepted Values Mandatory Description
Hostname   Y FTP Server Hostname.
Port   N FTP Server Port. Defaults to port 21 if not set.
Username   Y FTP Server Username.
Password   Y FTP Server Password.

HTTP API Notification Settings

The HTTP API Notification settings are available when API Notification is selected as delivery method. The URL entered will be contacted each time a new feed is available containing the URL that can be used to retrieve the actual data. The URL is send as a HTTP POST parameter named 'url'. The notification process expects to receive HTTP Response Code 200 on success within 10 seconds, otherwise it will try to re-deliver the feed later.

Configuration Parameter Accepted Values Mandatory Description
URL   Y The URL to be contacted once a new feed is available.

Have a question? Contact us at emis.com/contact